../courses.php

Procedural PHP

PHP

90

Breaking PHP Into Files

What require_once actually tracks, and what it does not.

A site's main page and its admin page both pull in the exact same shared file using require_once "functions.php"; in each place. A line is added at the very top of that shared file, outside any function, meant to run once per page. Instead, on some pages, it visibly runs twice. require_once is supposed to prevent loading the same file twice. Why would it still run that line's code twice on one page?

require_once prevents the exact same path string from being loaded twice within one request. It compares paths as text, not file contents. If that file gets pulled in from two different-looking paths that both happen to resolve to the same actual file, such as a relative path from one folder and a slightly different relative or absolute path from another, PHP's tracking can treat them as two distinct files, requiring each path once and running that file's top-level code twice in total.

require and include both pull the contents of another PHP file into the current one, at the exact spot the line appears, as if that file's contents were typed directly into that location.

require stops the entire script immediately, with a fatal error, if the file cannot be found. include only produces a warning in that situation and lets the rest of the script keep running without whatever that file would have defined.

Adding _once, as in require_once or include_once, tells PHP to skip loading that exact path again if it has already been loaded earlier in the same request, which matters most for files that define functions or classes.

A file pulled in this way does not get its own separate, protected set of variables. It shares the same variable scope as the file that pulled it in, at that exact point in the program.

A relative path written inside a require or include line is resolved relative to the file that line is actually written in, not relative to whichever address a visitor originally requested.

Two files working together: a shared functions file, and the page that uses it

The first block, defining format_price(), is written exactly once, inside a file commonly named something like functions.php. The second block, inside a different file such as index.php, never repeats that function's own code. It only calls it by name after pulling it in with require_once.

require_once "functions.php" checks whether that exact path has already been loaded earlier in this same request. If some other part of the page already required that same path string before this line ran, this second require_once does nothing at all, and no error occurs either way.

number_format( $amount, 2 ) is a built-in function, not one this program wrote. It rounds and formats a number to exactly 2 digits after the decimal point and adds thousands separators, which is why 49.5 becomes the text "49.50", not "49.5".

$total is created in the second file, after functions.php has already been pulled in, so by the time $total = 49.5; runs, format_price() already exists and is ready to be called. Calling it before that require_once line would fail, because the function would not exist yet.

require_once stops the page entirely with a fatal error if functions.php cannot be found at all at the given path. include_once, used the same way, only produces a warning and lets the rest of the page keep running without that file's functions defined.

require_once tracks file paths as text, not file contents

Requiring the exact same file through two different-looking path strings, one from one folder and a different relative path from another that happens to point at the same actual file, can cause that file's top-level code to run twice on a single page, because require_once's duplicate-protection compares the resolved path strings, not whether the underlying file is identical.

A missing required file stops the whole page, immediately

require and require_once both produce a fatal error and stop the rest of the script from running at all, the moment the file cannot be found. A visitor sees a broken or blank page rather than a page merely missing one feature, which is why require is generally preferred over include for anything the rest of the page genuinely cannot work without.

An included file can see, and overwrite, variables already in scope

A file pulled in with require or include does not get a separate, protected set of variables. If functions.php happened to contain a line like $total = 0; outside any function, that line would overwrite the including file's own $total the moment it ran, exactly as if both lines were typed into one file.

Functions and classes cannot be defined twice in one request

If two different included files both happen to define a function with the exact same name, such as format_price(), the second one to load causes a fatal cannot-redeclare error. This is one of the most common reasons require_once, rather than plain require, matters once a project grows past a single shared file.

The folder a script runs from is not always the folder the file sits in

A relative path such as require "functions.php" is resolved relative to the file containing that exact line, not relative to whichever address the visitor originally requested. Moving a file into a subfolder without updating its require paths is a common reason an otherwise unchanged file suddenly cannot find something it required successfully for months.

Using require for a shared functions file

Using require_once to guarantee it only loads once

When an AI tool writes code that pulls in another file, three things are worth checking. First, does it use require_once, not plain require, for any file defining functions or classes that might get pulled in from more than one place. Second, does a relative path inside a required file assume one specific calling location that might not always be true. Third, does an included file avoid defining a top-level variable name, such as $total, that could collide with one already in scope in the file that includes it.

Require functions.php twice in a row with plain require instead of require_once, and read the exact wording of the fatal error this produces.

Add a second function to functions.php with the exact same name as one already there, and observe which specific error PHP gives, and how early it appears.

Create a path on purpose that does not exist, and compare the error from require against the warning from include in the exact same spot.

Add a top-level $total = 0; line directly inside functions.php, outside any function, then check whether it changes the $total value already set in the including file.

Move functions.php into a subfolder without changing the require_once path in the including file, run the page, and read the resulting error to identify exactly what it is telling you.

Using include or include_once for a file the rest of the page genuinely cannot work without, so a missing file produces a confusing partial page instead of a clear, immediate failure.

Writing a relative require path that only works when the page is requested from one specific folder, then breaking it the moment the same file gets included from a script in a different folder.

Defining the same function name in two separate files that might both get loaded on the same page, relying on require_once everywhere to avoid a collision, instead of choosing distinct names from the start.

Putting code with visible side effects, such as printing something or modifying a variable, directly at the top level of a shared functions file, where every page that includes that file runs it too, often by accident.

Assuming a function defined in an included file is available immediately, even before the require or require_once line that pulls that file in actually runs, in the page's own top-to-bottom order.

You can now decide between require and include, and between the once and non-once versions, based on what should happen when a file is missing or already loaded. You can also explain why a relative path inside an included file depends on which file contains that line, not on the address a visitor originally requested.