PHP include e require

Um site de verdade tem dezenas de páginas, e todas repetem o mesmo cabeçalho, o mesmo menu e o mesmo rodapé. Copiar e colar esse HTML em cada página seria um pesadelo: para mudar um telefone, você teria que editar todas. Com include e require, você escreve o pedaço repetido uma vez, num arquivo separado, e manda o PHP "colar" esse arquivo onde precisar.

Os exemplos acontecem na máquina fictícia da Ana (ana@notebook), que está montando o site da sua lojinha de bolos. Antes desta aula, vale ter visto Funções e PHP Dentro do HTML.

A ideia: um carimbo

Pense num carimbo com o endereço da loja. A Ana não escreve o endereço à mão em cada envelope: ela carimba. Se a loja mudar de endereço, ela troca o carimbo, e todos os envelopes novos saem certos.

No PHP, o "carimbo" é um arquivo (cabecalho.php, por exemplo) e o ato de carimbar é a linha include 'cabecalho.php';. Quando o PHP encontra essa linha, ele:

1. procura o arquivo cabecalho.php;
2. lê o arquivo e executa o que estiver dentro, como se o código estivesse escrito ali, no lugar da linha do include;
3. continua o arquivo original da linha seguinte em diante.

Os nomes vêm do inglês: include = "incluir"; require = "exigir". A diferença entre "incluir" e "exigir" é justamente o que acontece quando o arquivo não está lá, como você vai ver.

O primeiro include

A Ana criou três arquivos na pasta inc. Primeiro, o cabeçalho:

<?php
echo "=== Lojinha da Ana ===\n";

Depois, o rodapé:

<?php
echo "--- (c) 2026 Lojinha da Ana ---\n";

E a página principal, que usa os dois:

<?php
include 'cabecalho.php';
echo "Bem-vindo! Hoje temos bolos e doces.\n";
include 'rodape.php';

include

A instrução "inclua aqui o arquivo…". Não é uma função: é uma palavra da própria linguagem, por isso não precisa de parênteses (escrever include('cabecalho.php'); também funciona, mas os parênteses são enfeite).

'cabecalho.php'

O nome do arquivo, entre aspas, como qualquer texto. Pode ser um caminho ('partes/cabecalho.php') ou uma variável.

;

Como toda instrução do PHP, termina com ponto e vírgula.

$ cd inc
$ php index.php
=== Lojinha da Ana ===                       « veio do cabecalho.php
Bem-vindo! Hoje temos bolos e doces.         « do próprio index.php
--- (c) 2026 Lojinha da Ana ---              « veio do rodape.php

O resultado é exatamente o mesmo que você teria se as três linhas echo estivessem no index.php. A vantagem: o cabeçalho e o rodapé agora podem ser usados por qualquer outra página.

As variáveis são compartilhadas

Como o código incluído "entra no lugar" do include, ele enxerga as variáveis que já existiam ali, e as variáveis que ele cria continuam existindo depois:

<?php
$titulo = "Promoções";
include 'mostra-titulo.php';
echo "De volta: $saudacao\n";

<?php
echo "Título recebido: $titulo\n";
$saudacao = "olá do arquivo incluído";

$ php variaveis.php
Título recebido: Promoções                 « o incluído leu $titulo
De volta: olá do arquivo incluído          « e criou $saudacao para o principal

Isso é muito usado para passar o título da página para o cabeçalho. Mas atenção: se o include estiver dentro de uma função, as variáveis do arquivo ficam presas dentro da função (é o escopo local):

<?php
function carrega(): void
{
    include 'config-var.php';     // config-var.php só tem: $loja = 'Lojinha da Ana';
    echo "Dentro da função: $loja\n";
}
carrega();
echo "Fora da função: $loja\n";

$ php dentro-func.php
Dentro da função: Lojinha da Ana

Warning: Undefined variable $loja in /home/ana/inc/dentro-func.php on line 8
Fora da função: 

Experimente: a página abaixo esqueceu de incluir o rodapé. Os três arquivos estão nas abas da caixa.

<?php
include 'cabecalho.php';
echo "Bem-vindo! Hoje temos bolos e doces.\n";

<?php
echo "=== Lojinha da Ana ===\n";

<?php
echo "--- Obrigada pela visita! ---\n";

<?php
include 'cabecalho.php';
echo "Bem-vindo! Hoje temos bolos e doces.\n";
include 'rodape.php';

include × require: quando o arquivo não existe

Os dois fazem a mesma coisa quando o arquivo existe. A diferença aparece quando ele não existe (nome errado, arquivo apagado, pasta errada). Veja o mesmo programa com cada um. O arquivo menu.php não existe:

<?php
include 'menu.php';
echo "A página continuou depois do include.\n";

$ php falta-include.php; echo "código: $?"

Warning: include(menu.php): Failed to open stream: No such file or directory in /home/ana/inc/falta-include.php on line 2

Warning: include(): Failed opening 'menu.php' for inclusion (include_path='.:') in /home/ana/inc/falta-include.php on line 2
A página continuou depois do include.        « o programa seguiu em frente
código: 0

Com include, o PHP dá dois avisos (Warning) e continua. Agora com require:

<?php
require 'menu.php';
echo "A página continuou depois do require.\n";

$ php falta-require.php; echo "código: $?"

Warning: require(menu.php): Failed to open stream: No such file or directory in /home/ana/inc/falta-require.php on line 2

Fatal error: Uncaught Error: Failed opening required 'menu.php' (include_path='.:') in /home/ana/inc/falta-require.php:2
Stack trace:
#0 {main}
  thrown in /home/ana/inc/falta-require.php on line 2
código: 255                                  « o echo nunca rodou

Com require, o PHP para tudo com um erro fatal (Fatal error). A linha do echo nunca é executada, e o programa termina com o código 255 (erro).

Lendo as mensagens

Qual usar?

Pergunte-se: a página faz sentido sem esse arquivo?

• Arquivo de funções, de configuração, a conexão com o banco, o cabeçalho com o <html>: sem eles a página quebra de qualquer jeito. Use require: é melhor parar logo, com uma mensagem clara, do que continuar e gerar dez erros confusos depois.
• Um pedaço opcional (um banner de promoção, um aviso que às vezes existe): use include, e a página segue sem ele.

Na prática, a maior parte do código PHP moderno usa require (ou require_once) quase sempre.

<?php
include 'menu.php';
echo "A página continuou.\n";

<?php
require 'menu.php';
echo "A página continuou.\n";

include_once e require_once: só uma vez

Às vezes o mesmo arquivo acaba sendo incluído duas vezes: a página inclui funcoes.php, e o cabeçalho, que ela também inclui, inclui funcoes.php de novo. Com um arquivo que só tem echo, o texto apareceria duas vezes. Com um arquivo que define funções, é pior:

<?php
function preco_com_desconto(float $preco): float
{
    return $preco * 0.9;
}

<?php
include 'funcoes.php';
include 'funcoes.php';
echo preco_com_desconto(20), "\n";

$ php duas-vezes.php; echo "código: $?"

Fatal error: Cannot redeclare function preco_com_desconto() (previously declared in /home/ana/inc/funcoes.php:2) in /home/ana/inc/funcoes.php on line 2
Stack trace:
#0 {main}
código: 255

"Cannot redeclare function" = "não é possível declarar a função de novo": uma função só pode ser criada uma vez. A versão _once ("uma vez") resolve: ela anota quais arquivos já foram incluídos e ignora os pedidos repetidos.

<?php
include_once 'funcoes.php';
include_once 'funcoes.php';     // ignorado: já foi incluído
echo preco_com_desconto(20), "\n";

$ php duas-once.php
18

Cabeçalho e rodapé de um site

Agora o uso mais comum de todos. A Ana quer que todas as páginas do site tenham o mesmo topo (com o menu) e o mesmo rodapé. Ela separa o HTML em três arquivos:

<!doctype html>
<html lang="pt-BR">
<head><meta charset="utf-8"><title><?= htmlspecialchars($titulo) ?></title></head>
<body>
<header>
  <h1>Lojinha da Ana</h1>
  <nav><a href="?pagina=inicio">Início</a> | <a href="?pagina=contato">Contato</a></nav>
</header>

<footer>
  <p>© <?= date('Y') ?> Lojinha da Ana — Campinas/SP</p>
</footer>
</body>
</html>

<?php
$pagina = $_GET['pagina'] ?? 'inicio';

$titulo = match ($pagina) {
    'contato' => 'Contato',
    default   => 'Início',
};

require __DIR__ . '/cabecalho.php';

if ($pagina === 'contato') {
    echo "<p>Fale com a Ana: (19) 99999-0000</p>\n";
} else {
    echo "<p>Bolos e doces feitos em casa.</p>\n";
}

require __DIR__ . '/rodape.php';

Repare que cabecalho.php e rodape.php são quase só HTML, com pequenos trechos <?= … ?>. E que o cabeçalho usa htmlspecialchars no título, como manda a aula Escapar a Saída. Com o servidor embutido rodando na pasta (php -S localhost:8000, em outro terminal), a Ana pediu a página de contato com o curl:

$ curl -s "localhost:8000/index.php?pagina=contato"
<!doctype html>
<html lang="pt-BR">
<head><meta charset="utf-8"><title>Contato</title></head>
<body>
<header>
  <h1>Lojinha da Ana</h1>
  <nav><a href="?pagina=inicio">Início</a> | <a href="?pagina=contato">Contato</a></nav>
</header>
<p>Fale com a Ana: (19) 99999-0000</p>                « a única parte que veio do index.php
<footer>
  <p>© 2026 Lojinha da Ana — Campinas/SP</p>
</footer>
</body>
</html>

O navegador recebe uma página única e completa: ele nem fica sabendo que ela foi montada a partir de três arquivos. Isso acontece no servidor, antes de a resposta sair.

<?php
$pagina = $_GET['pagina'] ?? 'inicio';

$titulo = match ($pagina) {
    'contato' => 'Contato',
    default   => 'Início',
};

require __DIR__ . '/cabecalho.php';

if ($pagina === 'contato') {
    echo "<p>Fale com a Ana: (19) 99999-0000</p>\n";
} else {
    echo "<p>Bolos e doces feitos em casa.</p>\n";
}

require __DIR__ . '/rodape.php';

<!doctype html>
<html lang="pt-BR">
<head><meta charset="utf-8"><title><?= htmlspecialchars($titulo) ?></title></head>
<body>
<header>
  <h1>Lojinha da Ana</h1>
  <nav><a href="?pagina=inicio">Início</a> | <a href="?pagina=contato">Contato</a></nav>
</header>

<footer>
  <p>© <?= date('Y') ?> Lojinha da Ana — Campinas/SP</p>
</footer>
</body>
</html>

<?php
$pagina = $_GET['pagina'] ?? 'inicio';

$titulo = match ($pagina) {
    'contato' => 'Contato',
    'sobre'   => 'Sobre',
    default   => 'Início',
};

require __DIR__ . '/cabecalho.php';

if ($pagina === 'contato') {
    echo "<p>Fale com a Ana: (19) 99999-0000</p>\n";
} elseif ($pagina === 'sobre') {
    echo "<p>Desde 2020 adoçando Campinas.</p>\n";
} else {
    echo "<p>Bolos e doces feitos em casa.</p>\n";
}

require __DIR__ . '/rodape.php';

<!doctype html>
<html lang="pt-BR">
<head><meta charset="utf-8"><title><?= htmlspecialchars($titulo) ?></title></head>
<body>
<header>
  <h1>Lojinha da Ana</h1>
  <nav><a href="?pagina=inicio">Início</a> | <a href="?pagina=sobre">Sobre</a> | <a href="?pagina=contato">Contato</a></nav>
</header>

Caminhos: onde o PHP procura o arquivo

Até aqui todos os arquivos estavam na mesma pasta. Mas sites crescem, e a Ana criou uma subpasta paginas/ dentro de inc/, com o arquivo sobre.php, que precisa do cabeçalho da pasta de cima:

<?php
include '../cabecalho.php';          // "suba uma pasta e pegue o cabeçalho"
echo "Sobre a loja: desde 2020.\n";

Rodando de dentro de paginas/, funciona. Rodando de outra pasta, não:

$ cd paginas
$ php sobre.php
=== Lojinha da Ana ===
Sobre a loja: desde 2020.
$ cd ..
$ php paginas/sobre.php

Warning: include(../cabecalho.php): Failed to open stream: No such file or directory in /home/ana/inc/paginas/sobre.php on line 2

Warning: include(): Failed opening '../cabecalho.php' for inclusion (include_path='.:') in /home/ana/inc/paginas/sobre.php on line 2
Sobre a loja: desde 2020.

Por quê? Um caminho que começa com ./ ou ../ é calculado a partir da pasta atual (a pasta onde o programa foi chamado, a do pwd), e não da pasta onde está o arquivo sobre.php. Quando a Ana estava em inc/, o ../ apontou para /home/ana, onde não há cabeçalho nenhum. Num servidor web acontece o mesmo: a "pasta atual" depende de qual script foi chamado, e um arquivo incluído por outro herda essa pasta.

A solução: __DIR__

__DIR__ é uma constante mágica: o PHP troca essa palavra pela pasta onde está o arquivo em que ela foi escrita, sempre como caminho completo. A irmã dela, __FILE__, é o caminho completo do próprio arquivo.

<?php
include __DIR__ . '/../cabecalho.php';
echo "Sobre a loja: desde 2020.\n";
echo __DIR__, "\n";
echo __FILE__, "\n";

$ cd ~
$ php inc/paginas/sobre2.php
=== Lojinha da Ana ===                       « funcionou mesmo chamado de /home/ana
Sobre a loja: desde 2020.
/home/ana/inc/paginas                        « __DIR__
/home/ana/inc/paginas/sobre2.php             « __FILE__

__DIR__

Vira '/home/ana/inc/paginas', não importa de onde o programa foi chamado. Duas sublinhas antes e duas depois.

.

O operador de concatenação: junta os dois textos.

'/../cabecalho.php'

O resto do caminho. Comece com /, porque __DIR__ não termina com barra. O resultado é /home/ana/inc/paginas/../cabecalho.php, que é o mesmo que /home/ana/inc/cabecalho.php.

include que devolve um valor: arquivos de configuração

Um arquivo incluído pode terminar com return, igual a uma função. O valor devolvido vira o resultado do include/require, e você pode guardá-lo numa variável. Esse é o jeito mais organizado de fazer um arquivo de configuração:

<?php
return [
    'loja'   => 'Lojinha da Ana',
    'cidade' => 'Campinas',
    'frete'  => 12.5,
];

<?php
$config = require 'config.php';
echo "Loja: {$config['loja']}\n";
echo "Frete: R$ " . number_format($config['frete'], 2, ',', '.') . "\n";
var_dump($config);

$ php usa-config.php
Loja: Lojinha da Ana
Frete: R$ 12,50
array(3) {
  ["loja"]=>
  string(14) "Lojinha da Ana"
  ["cidade"]=>
  string(8) "Campinas"
  ["frete"]=>
  float(12.5)
}

A vantagem sobre criar variáveis soltas no config.php (como $loja = '…';): fica claro, na página, de onde veio cada valor ($config['frete']), nenhuma variável aparece "do nada" e o arquivo funciona igual dentro de funções.

O que o include devolve quando não há return

<?php
$a = include 'rodape.php';
var_dump($a);
$b = @include 'naoexiste.php';
var_dump($b);
$c = include_once 'rodape.php';
var_dump($c);

$ php retorno.php
--- (c) 2026 Lojinha da Ana ---
int(1)          « deu certo e o arquivo não tem return: devolve 1
bool(false)     « o arquivo não existe: devolve false (o @ escondeu os Warnings)
bool(true)      « include_once de um arquivo já incluído: devolve true e não inclui

O @ na frente do include é o operador que silencia os avisos daquela linha. Use com muito cuidado (veja Tipos de Erro): esconder um aviso não conserta o problema.

<?php
$config = require __DIR__ . '/config.php';
echo "Loja: {$config['loja']}\n";
echo "Frete: R$ " . number_format($config['frete'], 2, ',', '.') . "\n";

<?php
return [
    'loja'   => 'Lojinha da Ana',
    'cidade' => 'Campinas',
    'frete'  => 12.5,
];

<?php
$config = require __DIR__ . '/config.php';
echo "Loja: {$config['loja']}\n";
echo "Frete: R$ " . number_format($config['frete'], 2, ',', '.') . "\n";
echo "Cidade: {$config['cidade']}\n";

<?php
return [
    'loja'   => 'Lojinha da Ana',
    'cidade' => 'Campinas',
    'frete'  => 15.0,
];

Quando dá errado

$ php paginas/sobre.php

Warning: require(../cabecalho.php): Failed to open stream: No such file or directory in /home/ana/inc/paginas/sobre.php on line 2

Fatal error: Uncaught Error: Failed opening required '../cabecalho.php' (include_path='.:') in /home/ana/inc/paginas/sobre.php:2
Stack trace:
#0 {main}
  thrown in /home/ana/inc/paginas/sobre.php on line 2

Fatal error: Cannot redeclare function preco_com_desconto() (previously declared in /home/ana/inc/funcoes.php:2) in /home/ana/inc/funcoes.php on line 2

Warning: Undefined variable $loja in /home/ana/inc/dentro-func.php on line 8

Referência

Exercícios

Resumo

• include e require "colam" outro arquivo PHP no lugar da linha e o executam, compartilhando as variáveis.
• Arquivo inexistente: include dá Warning e continua; require dá Fatal error e para. Use require para o que é indispensável.
• _once evita incluir o mesmo arquivo duas vezes (e o erro Cannot redeclare function). Use require_once para arquivos de funções e classes.
• Cabeçalho e rodapé em arquivos separados: muda num lugar, muda no site inteiro.
• Caminhos com ../ dependem da pasta atual; escreva __DIR__ . '/arquivo.php'.
• Um arquivo pode terminar com return [...], e $config = require 'config.php'; guarda o valor.
• Nunca inclua um nome vindo do usuário: use uma lista de páginas permitidas.

Próxima aula: Ler e Escrever Arquivos, para o PHP guardar e ler os seus próprios dados em arquivos de texto.