Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.syntblaze.com/llms.txt

Use this file to discover all available pages before exploring further.

The include_once statement is a PHP language construct that evaluates and incorporates a specified file into the current script during execution. It differs from the standard include statement by maintaining an internal registry of included files; before attempting an inclusion, PHP verifies if the file has already been loaded during the current request. If it has, PHP bypasses the operation, preventing fatal errors caused by duplicate declarations of functions, classes, or interfaces.

​
Syntax

Because include_once is a language construct and not a standard function, parentheses are optional. 
include_once 'path/to/file.php';

// Parentheses are permitted but generally discouraged for language constructs
include_once('path/to/file.php');

​
Execution Mechanics

Path Resolution PHP resolves the target file path based on the include_path directive defined in php.ini. If the file is not found within the include_path, PHP falls back to checking the directory of the calling script, followed by the current working directory. Absolute paths and explicitly relative paths (those starting with ./ or ../) bypass the include_path resolution entirely. Error Handling If PHP cannot locate or access the specified file, include_once emits an E_WARNING and allows script execution to continue. This contrasts with require_once, which emits an E_WARNING for the failed stream open followed by a fatal E_COMPILE_ERROR that halts script execution entirely. Because require_once emits a compile error rather than throwing an Error exception, the failure cannot be caught using a try...catch block. Return Values The construct evaluates to different values based on the inclusion state:
  • Initial Success: Returns 1 by default. If the included file contains a return statement in the global scope, include_once evaluates to that specific returned value.
  • Already Included: Returns boolean true if the file was previously included during the current request.
  • Failure: Returns boolean false if the file cannot be found or read.
// Assuming 'config.php' returns an array: return ['debug' => true];
$config = include_once 'config.php'; // $config is ['debug' => true]

// Subsequent call during the same request
$status = include_once 'config.php'; // $status is true (boolean)

​
Scope Inheritance

When a file is included, the code within it inherits the variable scope of the exact line where the include_once statement is executed.
  • Variables: Any variables available at the invocation line in the calling file are accessible within the included file. If include_once is called within a function, the included code behaves as if it were defined inside that function, restricting its variables to that local scope.
  • Functions and Classes: Regardless of where the include_once statement is executed (even within a local function scope), all functions and classes defined within the included file are automatically injected into the global scope.
  • Magic Constants: Magic constants like __FILE__ and __DIR__ evaluated inside the included file will resolve to the path and directory of the included file, not the calling file.
Master PHP with Deep Grasping Methodology!Learn More