PHP DO BÁSICO AO AVANÇADO – AULA 23 – Controle do fluxo de saída (buffers), funções externas (FFI) e Detalhes do CORE do PHP
A FFI é uma extensão experimental, lançada junto com o PHP7 e que permite carregar bibliotecas compartilhadas (.DLL ou .so), chamar funções C e acessar estruturas de dados C em PHP puro, sem ter que ter conhecimento profundo da API de extensão Zend, e sem ter que aprender uma terceira “ linguagem intermediária ”, isso nos auxilia em desenvolvimentos de aplicações que precisem utilizar algum hardware específico do Servidor, ou se comunicar com processos existentes e implementados em outras linguagens de programação, de maneira mais rápida e direta que pelo uso de APIs baseadas em texto. Já as funções de controle de buffer de saída, permitem armazenar ou controlar o momento exato de enviar a saída do script para a saída definida, isto pode ser útil em várias situações diversas, especialmente se você precisa enviar cabeçalhos para o browser depois que seu script começou a enviar dados, ou para tratar e produzir saídas em formatos diferentes do HTML ou do padrão definido.
Controle do Fluxo de Saída (Buffers)
As funções de controle de saída não afetam os cabeçalhos enviados usando header() ou setcookie(), somente afetam funções como echo e dados entre blocos de código PHP se existirem. Estas funções não precisam de nenhuma configuração especial e fazem parte do “CORE” do php, e algumas configurações do php.ini podem ajustar ou afetar seu comportamento são elas:
output_buffering (OFF, ON ou um VALOR INTEIRO) – Você pode ativar o buffer de saída para todos os arquivos definindo esta dretiva para ‘On’. Se você quiser limitar o tamanho do buffer para um certo limite – você pode usar um número máximo de bytes ao invés de ‘On’, como valor para esta diretiva (ex., output_buffering=4096 para um buffer de 4Kb). Deixar esta diretriz indefinida ou vazia pode comprometer funções que precisam realizar o envio de cookies, e headers como set_cookie() e header().
output_handler (nome_da_funcao) – Redireciona toda a saída do seu script para uma função, definida pelo nome_da_funcao. Por exemplo, se você definir set output_handler para mb_output_handler(), a codificação dos caracteres será transparentemente convertida para a codificação especificada. Definindo qualquer função para gerenciar a saída ativa o buffer de saída. Somente funções nativas podem ser usadas com esta diretiva. Para funções definidas pelo usuário, use ob_start() visto mais adiante.
implicit_flush (ON/OFF) – Mudando isto para true (o padrão é false) diz ao PHP para para descarregar a saída a si mesma automaticamente a cada bloco de saída. Isto é equivalente a utilizar a função flush() a cada print ou echo e a cada bloco de HTML. Ativar essa função em um ambiente de produção pode ter uma séria implicação na performance devido as opções de compactação automáticas (GZIP / ZIP) dos servidores HTTP e geralmente é recomendada apenas para o debug. O valor padrão é true quando operando sobre CLI SAPI.
url_rewriter.tags (STRING) – Especifica quais tags HTML serão reescritas por valores de output_add_rewrite_var(). Por padrão reescreve a=href,area=href,frame=src,input=src,form=form senque que form é uma tag especial, onde <input hidden=”session_id” name=”session_name”> é adicionada como uma variável de formulário. Disponível somente no PHP7 e PHP8
url_rewriter.hosts (STRING) – Especifica quais nomes de hosts são reescritos para incluir valores de output_add_rewrite_var(). Por padrão reescreve $_SERVER[‘HTTP_HOST’]. Vários hosts podem ser especificados, separados por “,” e sem espaços entre os nomes.
Algumas das funções de controle de fluxo, fazem uso de valores definidos em algumas das CONSTANTES MÁGICAS DO PHP, que já vem definidas por padrão no CORE do PHP, são elas:
PHP_OUTPUT_HANDLER_START
– Indica que o buffer de saída foi iniciadoPHP_OUTPUT_HANDLER_WRITE
– Indica que o buffer de saída está sendo liberado e tinha dados para enviar.PHP_OUTPUT_HANDLER_FLUSH
– Indica que o buffer foi liberado.PHP_OUTPUT_HANDLER_CLEAN
– Indica que o buffer de saída foi limpo.PHP_OUTPUT_HANDLER_FINAL
– Indica que esta é a operação de buffer de saída final.PHP_OUTPUT_HANDLER_CONT
– Indica que o buffer foi liberado, mas o buffer de saída continuará. É um alias paraPHP_OUTPUT_HANDLER_WRITE
PHP_OUTPUT_HANDLER_END
– Indica que o buffer de saída foi encerrado. É um alias paraPHP_OUTPUT_HANDLER_FINAL
PHP_OUTPUT_HANDLER_CLEANABLE
– Controla se um buffer de saída criado por ob_start () pode ser limpo.PHP_OUTPUT_HANDLER_FLUSHABLE
– Controla se um buffer de saída criado por ob_start () pode ser liberado.PHP_OUTPUT_HANDLER_REMOVABLE
– Controla se um buffer de saída criado por ob_start () pode ser removido antes do final do script.PHP_OUTPUT_HANDLER_STDFLAGS
– O conjunto padrão de sinalizadores de buffer de saída; atualmente equivalente a PHP_OUTPUT_HANDLER_CLEANABLE | PHP_OUTPUT_HANDLER_FLUSHABLE | PHP_OUTPUT_HANDLER_REMOVABLE no PHP8
No trecho abaixo, vemos um exemplo básico de como o crontrole de fluxo funciona:
<?php ob_start(); echo "Olá, Mundo!\n"; setcookie("cookiename", "cookiedata"); ob_end_flush(); ?>
Neste caso a saída “OLA MUNDO!” será armazenada no buffer de saída, e somente será disparada ao browser, quando ob_end_flush() for chamada. Abaixo vamos ver todas as funções de controle de fluxo detalhadamente. Já, ob_get_contents() captura o valor do buffer de saída aberto para uma variável.
Funções do Controle de Fluxo de Saída
flush()
Esta função tem o objetivo de descarregar todo e qualquer conteúdo que esteja no buffer diretamente para o servidor web (para ser encaminhado ao browser), tentando empurrar toda a saída diretamente. Porém, ela não tem efeito sobre o buffer do servidor ou do browser do cliente, ou seja, vários servidores principalmente os baseados em Win32 ainda vão usar o seu próprio buffer antes de vazera saída, fazendo com que ela não tenha um funcionamento efetivo. Alguns MODs do apache, como mod_gzip também vão segurar o buffer do lado do servidor, afim de tentarem realizar a compressão ou manipulação do conteúdo. Já browsers como o Internet Explorer aguardam um determinado número de bytes minimo para começarem a fazer a saída em tela, outros como o NETSCAPE e SAFARI em algumas versões aguardam que tags de abertura e fechamento estejam totalmente enviadas para renderizarem o conteúdo. Portanto, não confie totalmente neste fluxo de saída para realizar saídas grandes ou processos demorados.
Em tempo, se você usar flush no php-fpm com o Apache mod_proxy_fcgi, você precisa adicionar flushpackets = on
para habilitar o flush, e flushwait = n onde n está em milissegundos para atrasar o tempo de liberação para N segundos. Esses valores podem ser anexados à diretiva <Proxy>, por exemplo, <Proxy "fcgi://localhost /" flushpackets = on flushwait = 500>
ou nas linhas ProxyPass e ProxyPassMatch.
ob_start($callBackFunction, $tamanho, $opções)
Ativa o buffer de saída (captura), enquanto o buffer de saída estiver ativo, nada é enviado a saída do script (browser ou stdout), somente os cabeçalhos(headers e cookies) são enviados e a saída é guardada em um buffer interno, que pode ser manipulado. O conteúdo deste conteúdo pode ser capturado para uma variável para posteriormente ser utilizado, ou ser descartado ou retrabalhado (processado) e enviado ao browser do cliente em outro momento.
Buffers de saída são empilháveis, ou seja, você pode utilizar ob_start() enquanto outro ob_start() estiver ativo, a única regra aqui é que o programador tenha certeza de utilizar ob_end_flush() o número apropriado de vezes, e se múltiplas funções de callback de saída estiverem ativas, a saída será filtrada sequencialmente através de cada uma delas na ordem de aninhamento.
Uma função de callback pode ser especificada, e função deve receber um parâmetro string e deve retornar uma string, esta função é chamada quando o buffer é descarregado (flush), limpo ( ob_clean() ou outra função similar) ou quando o buffer de saída for descarregado ao final da requisição(request). Quando output_callback for chamada ela irá receber o conteúdo do buffer como seu parâmetro e é esperado que ela retorne um novo buffer de saída como resultado, o qual será enviado para o navegador. ob_end_clean()
, ob_end_flush()
, ob_clean()
, ob_flush()
e ob_start()
não podem ser chamados de dentro da função callback, chamá-las pode tornar o comportamento do php indefinido, se precisar limpar o conteúdo do buffer, retorne “” (a l string null) de dentro da função callback.
Se o parâmetro opcional $tamanho é informado, o buffer será descarregado em qualquer ponto de saída que faça o buffer ter dados de tamanho igual ou maior que $tamanho bytes. O valor padrão é 0, que significa que o função de output só será chamada quando o buffer de saída é fechado.
O parâmetro $opcoes é um bitmask que controla as operações que podem ser realizadas no buffer de saída. O padrão é permitir que o buffer possa ser limpo, descarregado ou removido, o que pode ser configurado explicitamente como PHP_OUTPUT_HANDLER_CLEANABLE
| PHP_OUTPUT_HANDLER_FLUSHABLE
| PHP_OUTPUT_HANDLER_REMOVABLE
, ou pelo atalho PHP_OUTPUT_HANDLER_STDFLAGS que englobas as 3.
O motivo mais comum de uso de ob_start é coletar dados que, de outra forma, seriam enviados ao navegador, seja para ter mais controle sobre a saída. Usando as funções de buffer de saída, por exemplo em casos de erros, você pode simplesmente deletar o buffer e enviar apenas a mensagem de erro. O motivo pelo qual o buffer de saída foi inventado é criar uma transferência contínua, do: php -> apache -> sistema operacional -> usuário da web, se cada um usa o mesmo tamanho de buffer, o sistema usará menos gravações, usará menos recursos do sistema e será capaz de lidar com mais tráfego.
ob_flush()
Descarrega o buffer de saída, ou seja, vai enviar todo o conteúdo do buffer armazenado para a saída padrão, se precisar capturar a saída, você deve chamar on_get_contents() antes de chamar ob_flush, esta função não destroi a saída somente a envia para o browser ou console em caso de uso pela interface de linha de comando, e mantém a captura do buffer como um ‘novo’ buffer.
ob_end_flush()
Similar a função anterior, vai descarregar todo o buffer de saída, e fechar o buffer, ou seja, toda e qualquer saída gerada após a chamada a ob_end_flush() será descarregada diretamente para o browser/saida padrão. A função retorna true quando é bem sucedida em descartar o buffer, false se não, uma das razões de falha é utilizar a função sem um buffer ativo ou por algum motivo o buffer não pode ser excluído por estar travado ou em espera.
ob_clean()
Limpa o buffer de saída, descartando seu conteúdo, ela não finaliza o buffer, somente o limpa até o ponto atual e continua armazenando seu conteúdo.
ob_end_clean()
De maneira análoga a anterior, essa função vai limpar o conteúdo existente e finalizar o fluxo de buffer, ou seja, a partir de sua chamada, todo e qualquer conteúdo a ser impresso, será enviado diretamente para o browser ou para a saída padrão.
ob_get_contents()
Captura o conteúdo do buffer de saída atual para uma variável. Ela retorna FALSE caso o buffer não esteja iniciado. Lembre-se que essa função captura o conteúdo atual do buffer, ou seja, se continuar havendo saída neste buffer e posteriormente outra captura, o conteúdo será o da captura original + a saida atual. Para finalizar o fluxo é necessário chamar funções de fechamento ou limpeza do buffer.
ob_get_clean()
Obtém o conteúdo do buffer e exclui o buffer de saída atual, deve ser usado por exemplo para capturar o buffer de saída para uma variável. Esta função tem exatamente o mesmo efeito de executar: ob_get_content(); ob_end_clean();
em sequencia. Lembre-se que não é uma boa prática finalizar ou limpar um buffer que não tenha sido iniciado por você, por exemplo, limpar todos os buffer ao inicio do script, pois o servidor web pode ter iniciado um fluxo de dados, com os headers próprios da resposta do servidor, antes de ter invocado seu script PHP.
ob_get_flush()
Captura e descarrega o buffer atual, ou seja, além de gravar o conteúdo na variável, também faz a saída para o browser ou saída padrão. Esta função é util, por exemplo para criar cache de conteúdos que sejam demorados para serem processados, por exemplo, você renderizou uma imagem com um gráfico das vendas do mês anterior, que demanda uma quantidade significativa de processamento e tempo, porém, uma vez gerada não vai ser alterada, então você pode simplesmente fazer a saída para o browser, ao mesmo tempo que captura e salva em um arquivo para uso em cache por exemplo.
ob_get_length()
Retorna o tamanho do buffer de saída em bytes, ou 0 se ele estiver vazio, ou FALSE caso ele não esteja iniciado. O trecho de código abaixo produz a saída 6, 11
na saída padrão
<?php ob_start(); echo "Hello "; $len1 = ob_get_length(); echo "World"; $len2 = ob_get_length(); ob_end_clean(); echo $len1 . ", ." . $len2; ?>
ob_get_status()
Esta função visa criar uma matriz com os devidos conteúdos de buffer atuais, se estes estiverem iniciados, porém, seu funcionamento desde o PHP7 é experimental, e aparentemente, mesmo no PHP8.1 continua apresentando dados incompletos ou incorretos e depender dela que não seja para fins de debug ou monitoramento não é aconselhado. O array retornado se parece com:
Array ( [name] => default output handler [type] => 0 [flags] => 112 [level] => 1 [chunk_size] => 0 [buffer_size] => 16384 [buffer_used] => 0 )
Onde os valores não estão presentes em nenhuma documentação do PHP
ob_get_level()
Retorna o nível do mecanismo de buffer de saída, ou seja, o nível de manipuladores de buffer aninhados ou zero se o mecanismo de buffer de saída não estiver ativado. Se no inicio da execução, você obter um valor 1 significa que a diretiva output_buffering está definida e ligada, ou seja, o fluxo de saída esta sendo automaticamente capturado. Este nível de saída é util, principalmente se você estiver usando um gerenciador de compactação como MOD_GZIP ou outro.
ob_gzhandler()
Esta é uma função de callback, ou seja, ela não é chamada diretamente, porém pode ser anexada a chamada de ob_start() como o callback para produzir uma saída compactada com GZIP. ob_gzhandler() é intencionalmente feita para ser usada como callback afim de facilitar o envio de dados gz-encoded para browsers que suportam páginas comprimidas. Antes de ob_gzhandler() enviar dados comprimidos, ela determina qual o tipo de códificação de conteúdo que o browser irá aceitar (“gzip”, “deflate” ou nenhum) e irá retornar a sua saída de acordo. Todos os browsers são suportados já que é dever do browser enviar o cabeçalho correto indicando que ele aceita paginas comprimidas.
Note, que se você estiver usando o suporte a páginas comprimidas, é muito mais eficiente usar a diretriz no php.ini ini.zlib.output_compression em níveis de recursos e de eficiência.
ob_implicit_flush(TRUE/FALSE)
Liga ou desliga o flush implícito, ou seja, se você não definir ela como desligado, toda e qualquer saída produzida pelo script será enviada diretamente ao browser ou a saída padrão. O padrão do PHP é que essa saída seja ON, ou seja, toda a saída é feita imediatamente, a não ser que a função ob_start() tenha sido chamada.
ob_list_handlers()
Retorna um array, com a pilha de buffers de saída, cada item do array, corresponde a um nível do aninhamento de buffers, e o respectivo valor é a função de callback atualmente atribuída ao controle de fluxo. Veja um exemplo:
<?php //usando output_buffering=On print_r(ob_list_handlers()); ob_end_flush(); ob_start("ob_gzhandler"); print_r(ob_list_handlers()); ob_end_flush(); // anonymous functions ob_start(function($string) { return $string; }); print_r(ob_list_handlers()); ob_end_flush(); ?>
Vai produzir a saída:
Array ( [0] => default output handler ) Array ( [0] => ob_gzhandler ) Array ( [0] => Closure::__invoke )
output_add_rewrite_var($nome, $valor)
Esta função adiciona ao fluxo de saída, valores de REWRITE, o nome e o valor serão adicionados aos URLs (como parâmetro GET) e formulários (como campos de entrada ocultos) da mesma forma que o ID da sessão quando a regravação de URL transparente estiver habilitada com session.use_trans_sid. O comportamento desta função é controlado pelos parâmetros url_rewriter.tags e url_rewriter.hosts no php.ini. Observe que essa função pode ser chamada com êxito no máximo uma vez por solicitação. Chamar esta função iniciará implicitamente o buffer de saída se ainda não estiver ativo.
output_reset_rewrite_vars()
Esta função limpa os pares de nove/valor definidos por output_add_rewrite_var.
Boas Práticas com Controle de Fluxo de Saída
O controle de fluxo de saída, tem como principal objetivo, permitir ao desenvolvedor um maior controle sobre o que fazer com saídas geradas em scripts, ou permitir a inclusão de scripts que produzam uma saída, como geradores e manipuladores de imagem, controle de fluxos de stream, geração de saídas em formatos diferentes como PDF ou XML ou XLS ou mesmo CSV e TXT com propósitos diversos.
O controle de fluxo, pode ser usado em conjunto com mecanismos de CACHE e APCU para um controle de conteúdo previamente renderizado, ou mesmo para mecanismos de cache diferenciados.
FFI – Foreign Function Interface – Interface de Funções Exteriores
Esta extensão é EXPERIMENTAL e foi introduzida no PHP 7, o comportamento e as funções ou qualquer outra documentação poderá mudar sem aviso em futuras versões do PHP, portanto verifique antes de fazer uso extensivo em ambientes ou tornar-se dependente dela.
Esta extensão permite carregar bibliotecas compartilhadas (.DLL ou .so) e chamar funções escritas em C ou em outras linguagens, ou mesmo acessar estruturas de dados do C em PHP puro, sem ter que ter conhecimento profundo da API de extensão Zend, e sem ter que aprender uma terceira “ linguagem intermediária ”. A API pública é implementada como uma única classe FFI com vários métodos estáticos (alguns deles podem ser chamados dinamicamente) e métodos de objetos sobrecarregados, que realizam a interação real com os dados C.
FFI é uma extensão perigosa, pois permite a interface com o sistema operacional e com o hardware da máquina em um nível muito baixo, se comparado as funções existentes nativamente no PHP, e só deve ser usada por desenvolvedores com conhecimento prático de linguagem C e das APIs C usadas. Para minimizar o risco, o uso da API FFI pode ser restrito com a diretiva ffi.enable php.ini em ambientes compartilhados.
Atualmente, acessar estruturas de dados FFI é significativamente (cerca de 2 vezes) mais lento do que acessar matrizes e objetos PHP nativos, não faz sentido usar a extensão FFI para velocidade, porém, pode fazer sentido usá-lo para reduzir o consumo de memória, e para iteração com hardwares especialistas ligados a máquina, que possam ser usados e compartilhados pelo ambiente web onde o uso do PHP é recomendado.
Para habilitar a extensão FFI, o PHP deve ser configurado com –with-ffi. Os usuários do Windows devem incluir php_ffi.dll no php.ini para habilitar a extensão FFI.
Uma amostra de como FFI funciona
Antes de mergulhar nos detalhes da API FFI, vamos dar uma olhada em alguns exemplos que demonstram a simplicidade do uso da API FFI para tarefas regulares. Alguns desses exemplos requerem libc.so versão 6 ou superior e, não funcionam em sistemas onde não está disponível. No ambiente Windows, ela requer que o Visual C Redistributable esteja instalado, e disponível para o SO e para o servidor WEB.
<?php // create FFI object, loading libc and exporting function printf() $ffi = FFI::cdef( "int printf(const char *format, ...);", // this is a regular C declaration "libc.so.6"); // call C's printf() $ffi->printf("Hello %s!\n", "world"); ?>
O exemplo acima irá imprimir Hello world! – E funciona em Ambiente LINUX/POSIX
Os objetos desta classe são criados pelos métodos 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. 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 de 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 da web. No entanto, é 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 FFI_SCOPE especiais (por exemplo, #define FFI_SCOPE “foo” ””; o escopo padrão é “C”) e então carregados por FFI :: load () durante o pré-carregamento. Isso leva à criação de um vínculo persistente , que estará disponível para todas as solicitações a seguir por meio 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.
Não vamos entrar em detalhes do seu funcionamento, até porque o escopo deste curso é a linguagem PHP, porém, vamos deixar um resumo de suas funções, métodos e dados. Abaixo os iteradores com a linguagem C:
FFI::addr – Cria um ponteiro não gerenciado para dados C
FFI::alignof – Obtém o alinhamento
FFI::arrayType – Constrói dinamicamente um novo tipo de array C
FFI::cast – Executa uma 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 de um arquivo de cabeçalho C
FFI::memcmp – Compara áreas de memória
FFI::memcpy – Copia uma área de 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 dos dados ou tipos 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
Funções de Verificação e Informações do PHP em execução
Estas funções serão somente apresentadas e permitem ao programador obter informações sobre o PHP em si, configurações em tempo de execução, extensões carregadas, versão e muito mais. Através dessas funções é que são geradas as saídas como a da função phpinfo(); ou seja, permitem de maneira programática, verificar se uma determinada função ou extensão está carregada, por exemplo para retornar uma mensagem de erro se uma determinada extensão necessária não estiver disponível.
As constantes listadas abaixo estão sempre disponíveis como parte do núcleo do PHP, e podem ser impressas em tela para apresentarem suas informações.
Constante | Valor | Descrição |
---|---|---|
CREDITS_GROUP | 1 | Uma lista do núcleo de desenvolvedores |
CREDITS_GENERAL | 2 | Créditos em geral: design e conceito da linguagem, autores do PHP e do módulo SAPI. |
CREDITS_SAPI | 4 | Uma lista dos módulos API dos servidores para o PHP, e seus autores. |
CREDITS_MODULES | 8 | Uma lista dos módulos de extensão para o PHP, e seus autores. |
CREDITS_DOCS | 16 | Os créditos para a equipe de documentação. |
CREDITS_FULLPAGE | 32 | Normalmente usada em combinação com as outras opções. Indica que uma pagina HTML completa precisa ser mostrada incluindo a informação indicada pelas outras opções. |
CREDITS_QA | 64 | Os créditos para a equipe de controle de qualidade. |
CREDITS_ALL | -1 | Todos os créditos, equivalente a usar: CREDITS_DOCS + CREDITS_GENERAL + CREDITS_GROUP + CREDITS_MODULES + CREDITS_QA CREDITS_FULLPAGE. Gera uma pagina HTML completa com as tags apropriadas. Este é o valor padrão. |
Já as constantes abaixo, podem ser usadas como argumentos da PHPINFO para limitar a quantidade de informações que serão exibidas.
Constante | Valor | Descrição |
---|---|---|
INFO_GENERAL | 1 | A linha da configuração, localização do php.ini, data de construção, servidor web, sistema e mais. |
INFO_CREDITS | 2 | Créditos do PHP. Veja também phpcredits(). |
INFO_CONFIGURATION | 4 | Valores atuais e principais para as diretivas de configuração do PHP. Veja também ini_get(). |
INFO_MODULES | 8 | Módulos carregados e suas respectivas configurações. |
INFO_ENVIRONMENT | 16 | Informações das variáveis de ambiente que também estão disponíveis em $_ENV. |
INFO_VARIABLES | 32 | Mostra todas as variáveis pré-definidas a partir de EGPCS (Ambiente, GET, POST, Cookie, Server). |
INFO_LICENSE | 64 | Informação sobre a licença do PHP. |
INFO_ALL | -1 | Mostra tudo acima. Este é o valor padrão. |
assert_options($assert, $valor)
Define/Obtém várias opções do assert, se forem passados novos dados, estes serão atualizados e definidos, ou se ela for chamada, o array das opções e seus valores é retornado. Os valores póssiveis para $assert sâo:
opção | parâmetro do ini | padrão | descrição |
---|---|---|---|
ASSERT_ACTIVE | assert.active | 1 | ativa a avaliação de assert() |
ASSERT_WARNING | assert.warning | 1 | mostra um aviso do PHP para cada afirmação que falhar |
ASSERT_BAIL | assert.bail | 0 | termina a execução do script quando uma afirmação falhar |
ASSERT_QUIET_EVAL | assert.quiet_eval | 0 | desativa error_reporting durante a avaliação da expressão |
ASSERT_CALLBACK | assert.callback | (null ) |
função do usuário para chamar quando uma afirmação falhar |
<?php assert_options( ASSERT_CALLBACK, 'assert_callback'); function assert_callback( $script, $line, $message ) { echo 'Você tem uma falha estrutural no seu projeto em: <b>', $script,'</b> : linha <b>', $line,'</b> :<br />'; echo '<b>', ereg_replace( '^.*//\*', '', $message ), '</b><br /><br />'; echo 'Abra o arquivo fonte e verifique-o, porque não é um comportamento normal!'; exit; } $x = 3; assert('is_integer( $x ) && ($x >= 0) && ($x <= 10); //* $x must be an integer value from 0 to 10' ); echo "0 <= $x <= 10"; ?>
Asserts devem ser usadas apenas com a intenção de eliminar erros apenas. Você deve usa-las para testar condições que devam ser sempre true e que indiquem algum erro de programação ou para verificar a existência/disponibilidade de funções, extensões ou ainda de limites e recursos do sistema. Asserts não devem ser usadas para operações em tempo de execução normais como para conferir certo valor de entrada. Como uma dica de uso, o seu código deve funcionar corretamente mesmo que os asserts não estejam ativados.
assert() são particularmente úteis quando estiver criando sistemas automáticos para testes porque permitem que você capture facilmente o código passado para a afirmação em conjunto com informações sobre onde a afirmação foi feita. Enquanto esta informação pode ser capturada por outros métodos, usar afirmações torna muito mais fácil e rápido!
Conforme observado na Wikipedia – “as afirmações são principalmente uma ferramenta de desenvolvimento, muitas vezes são desativadas quando um programa é lançado ao público.” e “Asserções devem ser usadas para documentar situações logicamente impossíveis e descobrir erros de programação – se o ‘impossível’ ocorre, então algo fundamental está claramente errado. Isso é diferente do tratamento de erros, já que a maioria das condições de erro são possíveis, embora algumas possam ser extremamente improváveis de ocorrem na prática. Usar asserções como um mecanismo de tratamento de erros de uso geral geralmente não é aconselhável pois as asserções não permitem uma recuperação normal de erros e uma falha de asserção geralmente interrompe a execução do programa abruptamente. As asserções também não exibem um erro amigável.
cli_get_process_title()
Retorna o titulo do processo atual, e está disponível apenas no modo CLI.
dl($extension)
Carrega uma extensão do PHP durante a execução, o nome da extensão deve ser passado, e se estiver disponível ela será carregada, caso contrário não. Veja o exemplo:
<?php if (!extension_loaded('sqlite')) { if (strtoupper(substr(PHP_OS, 0, 3)) === 'WIN') { dl('php_sqlite.dll'); } else { dl('sqlite.so'); } } ?>
O trecho acima, carrega a extensão sqlite no windows ou em linux/posix caso ela não esteja carregada e esteja disponível. Note, que a função dl() pode ser desabilitada pelo php.ini e não permitir o uso, o ideal é verificar se a extensão necessária está carregada, e apresentar uma mensagem de erro amigavel antes de chamar as funções da extensão necessária.
extension_loaded($extensao)
Indica quando uma extensão esta carregada, retornando true caso esteja, ou false caso não. O nome das extensões pode ser obtido com phpinfo() ou com a execução de php -m
na linha de comando. Atenção, usa o nome interno da extensão para testar se uma extensão esta disponível ou não. A maioria dos nomes internos esta escrita em minúsculas mas algumas extensões podem ter letras maiúsculas. Tenha cuidado que esta função diferencia maiúsculas e minúsculas!
Funções da GC (coleta de lixo)
gc_collect_cycles() – Força a coleta de qualquer ciclo de lixo existente
gc_disable() – Desativa o coletor de referência circular ou coletor de lixo
gc_enable() – Ativa o coletor de referência circular ou coletor de lixo
gc_enabled() – Retorna o status do coletor de referência circular, true ligado ou false desligado
gc_mem_caches() – Recupera a memória usada pelo gerenciador de memória Zend Engine (limpa)
gc_status – Obtém informações sobre o coletor de lixo, retornando o estado atual de todos os objetos em memória.
get_cfg_var($configuracao)
Obtém o valor de uma opção de configuração do PHP especificada pelo $configuracao get_cfg_var retorna o valor de php.ini diretamente, enquanto ini_get retorna o valor de configuração do tempo de execução, ou definido pelo .htaccess ou outro método.
get_current_user()
Obtém o nome do dono do script PHP atual, ou seja, quem está executando o arquivo no servidor atual
get_extension_funcs($modulo)
Retorna uma matriz com os nomes de funções do módulo, veja o exemplo abaixo
<?php print_r(get_extension_funcs("xml")); ?>
O exemplo acima irá imprimir algo similar à:
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
[22] => utf8_encode
[23] => utf8_decode
)
get_include_path()
Obtém a opção de configuração include_path atual como uma string
get_included_files() ou get_required_files()
Retorna um array com os nomes dos arquivos incluídos ou requeridos, como uma pilha.
get_loaded_extensions(TRUE/FALSE)
Retorna uma matriz com os nomes de todos os módulos compilados e carregados, se o valor true for passado, retorna também as extensões ZEND o padrão éfalse
get_magic_quotes_runtime()
Obtém a configuração ativa para magic_quotes_runtime, retornando 0 para desativadas, ou 1 para ativadas
get_resources($recurso)
Retorna recursos ativos, se $recurso esta definido, isso fará com que get_resources () retorne apenas recursos de um determinado tipo passado. Uma lista de tipos de recursos está disponível caso não seja informado valores em forma de um array. Se a string passada for desconhecida sera retornado um false.
getenv($var)
Obtém uma variável de ambiente, ou false se não existir $ip = getenv("REMOTE_ADDR");
obtém o número ip do usuário, você poderá ver uma lista de todas as variáveis de ambiente usando phpinfo() e poderá encontram o que muitas delas indicam dando uma olhada em “CGI specification” , especialmente na “page on environmental variables”.
getlastmod()
Obtém a hora da última modificação da página (script) atual, se quiser obter a hora da última modificação de um arquivo diferente, considere usar filemtime()
getmygid()
Obtém o GID do dono do script PHP em execução (quem esta executando)
getmyinode()
Obtém o inode do script atual
getmypid()
Obtém o ID do processo PHP
getmyuid()
Obtém o UID do dono do script PHP
ini_alter($nome, $valor) ou ini_set($nome, $valor)
Define um novo valor para a opção de configuração indicada, a opção de configuração irá manter o novo valor durante a execução do script e será restaurado ao final da execução do script
ini_get_all($extensao)
Obtém todas as opções de configuração, como uma matriz associativa, se o parâmetro opcional $extensao estiver definido, apenas as opções especificas para esta extensão serão retornadas. A matriz retornada usa o nome da diretiva como chave da matriz sendo os os elementos global_value (definidos no php.ini), local_value (talvez definidos com ini_set() ou .htaccess), e access o nível de acesso
ini_get($var)
Obtém o valor de uma opção de configuração, com o nome $var. Em caso de falha, como tentar obter um valor que não exista, irá retornar uma string vazia. Um valor booleano off será retornado como uma string vazia enquanto um valor booleano on será retornado como “1”. Vários valores de definição de tamanho de memória, como upload_max_filesize são guardados no arquivo php.ini em uma anotação curta. ini_get() irá retornar exatamente a string guardada no arquivo php.ini, NÃO o seu valor inteiro equivalente. Tentar funções matemáticas comuns com estes valores não trará o resultado esperado.
ini_restore($var)
Restaura o valor de uma opção de configuração ao seu valor original
memory_get_peak_usage(TRUE/FALSE)
Retorna o pico de memória, em bytes, que foi alocado para seu script PHP. Se o valor passado for TRUE obtem o tamanho real da memória alocada do sistema. Se não for definido ou falso, apenas a memória usada por emalloc () é relatada, e este é o padrão.
memory_get_usage(TRUE/FALSE)
Retorna a memória que esta alocada para o script, ou seja a quantidade real usada pelo PHP na execução do script. Se true for passado usa a memória real do sistema, se false (o padrão) é usada a saida da função emalloc().
php_ini_loaded_file()
Retorna o caminho e o nome do arquivo incluído com as diretrizes do PHP.INI carregadas atualmente
php_ini_scanned_files()
Retorna uma lista dos arquivos ini interpretados a partir do diretório ini adicional, retorna uma lista separada por vírgula dos arquivos interpretados depois do php.ini. Estes arquivos são encontrados no diretório definido pela opção –with-config-file-scan-dir definida durante a compilação.
php_sapi_name()
Retorna uma string minúscula que descreve o tipo de interface entre o servidor web e o PHP (Server API, SAPI). Em CGI PHP, esta string é “cgi”, em mod_php para o Apache, esta string é “apache” e assim por diante, php-fpm pode ser ‘fcgi’ ou ‘php-fpm’.
php_uname()
Retorna informação sobre o sistema operacional que o PHP foi construído, em uma string. Se você quer apenas o nome do sistema operacional, considere usar a constante PHP_OS.
phpinfo()
Mostra uma grande quantidade de informações sobre o estado atual do PHP, incluindo informações sobre as opções de compilação e extensões, a versão do PHP, informações do servidor e ambiente se compilado como um módulo, o ambiente PHP atual, informação da versão do SO, caminhos, valores principais e locais das opções de configuração, cabeçalhos HTTP e a licença do PHP.
Devido a configuração do php em cada sistema ser diferente, a função phpinfo() e normalmente utilizada para conhecer as definições de configuração e as variáveis pré-definidas que estejam disponíveis no sistema phpinfo() é também é uma ferramenta valiosa para eliminação de erros já que contém todos os dados de EGPCS (Environment, GET, POST, Cookie, Server).
A saída pode ser configurada passando-se uma ou mais constants que serão somadas junto com o parâmetro opcional what. Pode combinar as respectivas constantes ou seus valores bit a bit juntos com o operador or
phpversion($ext)
Obtém a versão atual do PHP, se $ext for fornecida, a versão daquela extensão é retornada. Esta informação está também disponível na constante pré-definida PHP_VERSION.
putenv($envv)
Define o valor de uma variável de ambiente, adiciona $envv no ambiente do servidor, essa variável de ambiente irá existir somente durante a requisição atual, ao final da requisição o ambiente é retornado ao seu estado natural. Definir certas variáveis de ambiente pode ser potencialmente uma brecha de segurança, por isso a diretiva safe_mode_allowed_env_vars contém uma lista separada por vírgula de prefixos. No modo seguro, o usuário poderá alterar variáveis de ambiente cujo o nome comece por um dos prefixos indicados nesta diretiva. Por padrão os usuários só poderão definir varáveis que comecem com PHP_ Nota: se esta diretiva estiver vazia, o PHP permitirá ao usuário modificar QUALQUER variável de ambiente!
restore_include_path()
Restaura a opção de configuração include_path de volta para o seu valor principal definido no php.ini
set_include_path($path)
Define a opção de configuração include_path durante a execução do script. Através do uso da constante PATH_SEPARATOR, é possível estender o include path sem levar em consideração o sistema operacional.
set_time_limit($secs)
Limita o tempo de execução do script, se este limite é atingido, o script retorna um erro fatal. O limite padrão é de 30 segundos, ou se existir o valor definido o valor max_execution_time definido no php.ini. Se seconds for definido como zero, não é imposto nenhum limite. Quando utilizada, set_time_limit() reinicia o contador do limite do tempo a partir de zero.
sys_get_temp_dir()
Retorna o diretório definido como diretório temporário para arquivos e armazenamento
version_compare($v1, $v2, $operador)
A função primeiro substitui _, – e + por um ponto (.) nas strings de versão e também insere pontos antes e depois de qualquer valor não número de modo que, por exemplo, ‘4.3.2RC1’ se torne ‘4.3.2.RC.1’. Em seguida, ele compara as partes começando da esquerda para a direita. Se uma parte contém strings de versão especial, elas sã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 as 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 o estado de desenvolvimento. Retorna -1 se a primeira versão for inferior à segunda, 0 se forem iguais e 1 se a segunda for inferior
zend_thread_id()
Retorna um identificador único para a thread atual no motor ZEND. Esta função só está disponível se o PHP foi construído com suporte ZTS (Zend Thread Safety)