Download the PHP package jonbaldie/phpstan-extension-accessing-globals without Composer

PHPStan Extension: Accessing Globals

This project is a PHPStan extension for detecting code that accesses or modifies globally shared data in PHP, a common source of bugs and a violation of functional programming principles.

It helps you write cleaner, more predictable code by ensuring that functions and methods receive all their dependencies explicitly.

Features

This extension provides a set of rules to enforce restrictions on accessing and modifying global and superglobal variables:

• neverAccessGlobals: Disallows reading from global variables using the global keyword.
• neverModifyGlobals: Prevents modification of the $GLOBALS superglobal array.
• neverAccessSuperGlobals: Forbids accessing superglobal variables like $_GET, $_POST, $_SESSION, etc.
• neverModifySuperGlobals: Forbids modifying superglobal variables.
• neverAccessSuperGlobalsInNestedScope: A weaker version of neverAccessSuperGlobals that allows accessing superglobals in the root scope (e.g., in an index.php file) but not within functions, methods, or closures.
• neverModifySuperGlobalsInNestedScope: A weaker version of neverModifySuperGlobals that allows modifying superglobals in the root scope.

The extension also includes a more "opinionated" set of rules for teams that want to enforce a stricter, more functional style of programming:

• ForbidUsingGlobalConstants: Prevents functions from accessing global constants (define() or const), forcing them to be passed as arguments. This also covers dynamic lookups via constant(): a literal name is reported like a plain constant fetch, and a dynamic name is reported conservatively since it may resolve to a global constant.
• ForbidUsingStaticProperties: Prevents access to static properties, which are a form of global state.
• ForbidUsingClassConstants: Prevents a function from accessing a constant on another class, enforcing that the value should be passed in.
• ForbidImpureGlobalFunctions: Flags calls to impure global functions like time(), getenv(), or rand() that produce side effects or rely on hidden external state.

Installation

You can install this extension via Composer:

Usage

This extension comes with three pre-defined rule sets.

Default (Pragmatic) Rules

This is the recommended configuration for most projects. It prevents the use of the global keyword and modification of $GLOBALS, while allowing superglobals to be accessed and modified in the root scope (e.g., in your index.php file).

To enable the default rules, include rules.neon in your project's phpstan.neon configuration:

This enables the following rules:

• neverAccessGlobals - Detects use of the global keyword
• neverModifyGlobals - Detects modifications via $GLOBALS['key']
• neverModifyGloballyDeclaredVariables - Detects modifications to variables declared with global
• neverAccessSuperGlobalsInNestedScope - Allows superglobals in root scope only (accessing)
• neverModifySuperGlobalsInNestedScope - Allows superglobals in root scope only (modifying)

Note: A single line of code may trigger multiple rules. For example, global $db; $db = new PDO(...) will report both accessing the global variable AND modifying it, since these represent distinct problems that need different refactoring approaches.

Strict Rules

This configuration is for projects that want to enforce the highest level of strictness. It completely forbids any interaction with global or superglobal variables anywhere in your codebase.

To enable the strict rules, include rules-strict.neon instead:

This enables the following rules:

• neverAccessGlobals
• neverModifyGlobals
• neverAccessSuperGlobals
• neverModifySuperGlobals

Opinionated Rules

This is the strictest rule set, designed for projects that want to enforce a purely functional style where all dependencies are explicit. It helps eliminate hidden dependencies, side effects, and mutations.

To enable the opinionated rules, include rules-opinionated.neon:

This enables the following rules:

• ForbidUsingGlobalConstants
• ForbidUsingStaticProperties
• ForbidUsingClassConstants
• ForbidImpureGlobalFunctions

Working with Legacy Code

If you're applying this extension to an existing codebase with heavy global variable usage, here's what to expect:

Error Volume: A 3,000-line legacy script might have 50-100+ errors from the default rules. This is expected and represents real technical debt.

Recommended Approach:

1. Start with the default rules (rules.neon) - they're pragmatic and focus on the most problematic patterns
2. Focus on global keyword usage first - this reveals which functions share hidden state with each other
3. Tackle superglobal usage in functions next - superglobals at the top-level (e.g., in index.php) are allowed, but inside functions they create hidden dependencies
4. Skip the opinionated rules initially - they'll flag hundreds of issues like time(), rand(), and define() usage that aren't the critical problems

What each rule catches:

• neverAccessGlobals + neverModifyGlobals → Functions using global $x or $GLOBALS['x'] (the worst offenders)
• neverModifyGloballyDeclaredVariables → Assignments to variables after declaring them with global
• Superglobal rules → $_GET, $_POST, $_SESSION usage inside functions (root scope access is allowed)

The goal is to make dependencies explicit through function parameters and return values.

Custom Configuration

If you want to enable only a specific set of rules, you can copy the ones you need from the extension's config directory into your own phpstan.neon file.

Examples

This extension is designed to catch problematic patterns in your code. Here's what each rule detects:

Default Rules (rules.neon)

Strict Rules (rules-strict.neon)

Opinionated Rules (rules-opinionated.neon)

The key principle: Make all dependencies explicit through function parameters and return values.