PHPackages                             jonbaldie/phpstan-extension-accessing-globals - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Testing & Quality](/categories/testing)
4. /
5. jonbaldie/phpstan-extension-accessing-globals

ActiveLibrary[Testing & Quality](/categories/testing)

jonbaldie/phpstan-extension-accessing-globals
=============================================

PHPStan extension for detecting code that accesses or modifies globally shared data, a common source of bugs.

v0.3.1(7mo ago)09MITPHPCI passing

Since Oct 8Pushed 7mo agoCompare

[ Source](https://github.com/jonbaldie/phpstan-extension-accessing-globals)[ Packagist](https://packagist.org/packages/jonbaldie/phpstan-extension-accessing-globals)[ RSS](/packages/jonbaldie-phpstan-extension-accessing-globals/feed)WikiDiscussions main Synced 1mo ago

READMEChangelogDependencies (3)Versions (11)Used By (0)

PHPStan Extension: Accessing Globals
====================================

[](#phpstan-extension-accessing-globals)

This project is a [PHPStan](https://phpstan.org/) 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
--------

[](#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.
- **`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
------------

[](#installation)

You can install this extension via [Composer](https://getcomposer.org/):

```
composer require --dev jonbaldie/phpstan-extension-accessing-globals
```

Usage
-----

[](#usage)

This extension comes with three pre-defined rule sets.

### Default (Pragmatic) Rules

[](#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:

```
includes:
    - vendor/jonbaldie/phpstan-extension-accessing-globals/config/rules.neon
```

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

[](#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:

```
includes:
    - vendor/jonbaldie/phpstan-extension-accessing-globals/config/rules-strict.neon
```

This enables the following rules:

- `neverAccessGlobals`
- `neverModifyGlobals`
- `neverAccessSuperGlobals`
- `neverModifySuperGlobals`

### Opinionated Rules

[](#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`:

```
includes:
    - vendor/jonbaldie/phpstan-extension-accessing-globals/config/rules-opinionated.neon
```

This enables the following rules:

- `ForbidUsingGlobalConstants`
- `ForbidUsingStaticProperties`
- `ForbidUsingClassConstants`
- `ForbidImpureGlobalFunctions`

### Working with Legacy Code

[](#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

[](#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
--------

[](#examples)

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

### Default Rules (`rules.neon`)

[](#default-rules-rulesneon)

```