.PHP File Format – File structure

Text and encoding

PHP treats source as bytes. Any encoding whose bytes below 128 mean the same as ASCII works without any setting, and that includes UTF-8, the usual choice. Multi-byte encodings that reuse low bytes inside a character, such as Shift-JIS, need the zend.multibyte setting.

• Byte order mark. PHP does not skip a UTF-8 byte order mark. Before the first tag it is inline text, so it is sent as output, and a later declare(strict_types=1) or namespace statement fails because it is no longer the first thing in the file. Save PHP files as UTF-8 without a byte order mark.
• Line endings. LF and CRLF both work. Line endings inside string literals are kept exactly as they are in the file.
• Case in tags. Tags are not case-sensitive: <?PHP is the same as <?php.

PHP mode and inline HTML

A file starts in text mode, which the language calls inline HTML, although the text need not be HTML. Text in this mode is sent to the output unchanged. An opening tag switches to PHP mode. A closing tag switches back. A file can change mode any number of times.

<ul>
<?php foreach ($names as $name): ?>
  <li><?= htmlspecialchars($name) ?></li>
<?php endforeach; ?>
</ul>

Text between tags obeys the control structure it sits in: in an if whose condition is false it is skipped, and in a loop it repeats. For that reason templates often use the alternative syntax with colons, as above. The lexer returns the text as a T_INLINE_HTML token and the compiler turns it into an output instruction, so text mode is part of the program rather than something done before compiling.

Opening and closing tags

<?php echo "one" ?>
two
<?= "three" ?>

four

The shebang line

A script run from the command line on a Unix-like system may start with a #! line naming the interpreter. The command-line PHP skips that first line of the file it runs, so it is neither output nor compiled.

#!/usr/bin/env php
<?php
echo "Hello from the command line\n";

The line has no meaning to the language. It is for the operating system’s program loader, and only a file started directly from a shell needs it.

Stopping the compiler

__halt_compiler(); ends compilation at that point. Nothing after it is parsed, so a file can carry arbitrary data after its code. It may appear only at the outermost level of the file. The constant __COMPILER_HALT_OFFSET__ gives the byte position in the file where the data starts. Self-extracting PHP archives use this: the code at the top reads the data after it. The .phar format works this way, with a stub of PHP before the archive contents.

<?php
$data = file_get_contents(__FILE__, offset: __COMPILER_HALT_OFFSET__);
echo strlen($data), " bytes of data\n";

__halt_compiler();raw bytes can follow here

Declare directives

declare ( directive = literal {, directive = literal} ) ;
declare ( directive = literal {, directive = literal} ) statement
declare ( directive = literal {, directive = literal} ) : statements enddeclare ;

A declare statement sets a compile-time option. Directive values must be literals, because they are read at compile time. A constant or a variable is an error. Used as a statement ending in a semicolon, the directive applies to the rest of the file. Used with a block, it applies to the block. A declare in an included file does not affect the file that included it. See declare in the manual.

Several directives can be given in one statement, separated by commas.

Include and require

Four language constructs compile and run another file at the point where they appear. They are not functions, so the parentheses are optional and they cannot be called through a variable.

• The included file starts in text mode. Compilation of the included file begins in inline HTML, so its code must be inside PHP tags, whatever mode the including line was in.
• Path search. A path that is absolute, or that starts with ./ or ../, is used as given. Any other path is looked up through the include_path setting, then in the directory of the including script and the current working directory. __DIR__ . '/lib.php' avoids any ambiguity.
• Scope. Included code runs with the variable scope of the include line. Inside a function its top-level variables are local to that function. Functions and classes declared in it are always global (or in the file’s namespace).
• Return value. include gives 1 unless the file has a return statement at its top level, in which case it gives that value. A return stops running the included file and goes back to the includer, so files can act as configuration: $config = include 'config.php';.
• Precedence. include is a low-precedence prefix operator: include('a.php') == true parses as include (('a.php') == true). Parenthesise the whole expression instead: (include 'a.php') == true.
• Remote files. A URL can be included only if allow_url_include is on. It is off by default and deprecated, and a remote include runs whatever the other server returns.

Autoloading

Modern PHP programs rarely name the files they need. A class, interface, trait or enum can be loaded on first use instead: when PHP meets a name it has not seen, it calls each function registered with spl_autoload_register() in turn, giving it the fully qualified name, and each may include the file that declares it.

<?php
spl_autoload_register(function (string $class): void {
    $path = __DIR__ . '/src/' . str_replace('\\', '/', $class) . '.php';
    if (is_file($path)) {
        require $path;
    }
});

$report = new App\Reports\Monthly();  // loads src/App/Reports/Monthly.php

• An autoloader that cannot find the class should simply return, so that the next one can try. Throwing from an autoloader stops the chain, and the manual strongly discourages it.
• The older global function __autoload() was deprecated in PHP 7.2 and removed in 8.0. Use spl_autoload_register().
• Functions and constants are not autoloaded. Only class-like names are.
• PSR-4 is the common convention for mapping namespaces to folders, and Composer generates an autoloader from it, which a program loads with require __DIR__ . '/vendor/autoload.php';.

Typical layout

A file that declares a class usually follows this order. The first two items are required to come first if present; the rest is convention, set out in PER Coding Style.

<?php

declare(strict_types=1);

namespace App\Reports;

use App\Db\Connection;
use InvalidArgumentException;

use function strlen;

final class Monthly
{
    public function __construct(private Connection $db) {}
}

A file may declare several classes, and need not be named after any of them. The rule of one class per file named after the class is a convention that autoloaders rely on. Mixing declarations with code that does things, such as echoing output, works but is discouraged. See Namespaces for the rules on what may come before namespace.