README

GCWorld Globals provides a typed, filterable access layer for PHP superglobals. It supports automatic scalar coercion, explicit validation and sanitization, recursive array filtering, JSON decoding, UUID conversion, and configurable default values.

Version

4.1.0

Requirements

• PHP 8.4 or newer
• JSON extension
• mbstring extension

Installation

composer require gcworld/globals

Basic Usage

<?php

use GCWorld\Globals\Globals;

$globals = new Globals();

$_GET['page'] = '42';
$_GET['email'] = 'person@example.com';

$page = $globals->int()->GET('page');
$email = $globals->email()->GET('email');

Each explicit filter applies to the next value read. Filter state resets after the read, including when a callback throws. When multiple filters are selected before a read, the most recently selected filter wins.

Supported Superglobals

The following methods provide access to their corresponding PHP superglobals:

The target superglobal must exist as an array. For example, initialize the PHP session before using SESSION() in environments where $_SESSION has not yet been created.

Reading and writing values

$name = $globals->string()->POST('name');

$globals->SESSION('user_id', 42);
$globals->GET('optional', null);

Set operations return true when the selected global is available. Reads of a missing value return null unless defaults are enabled.

Inspecting and filtering a complete global

$keys = $globals->getKeys('GET');

$filtered = $globals->GET()->filterAll();
$unfiltered = $globals->GET()->filterNone();

filterAll() recursively applies automatic filtering. filterNone() returns the selected global without changing its values.

Automatic Filtering

Automatic filtering is enabled by default for reads that do not select an explicit filter. It recognizes:

• true, false, y, and n as booleans
• Valid integers without ambiguous leading zeroes
• Decimal numbers as floats
• Arrays, recursively
• Remaining scalar values as strings sanitized with FILTER_SANITIZE_SPECIAL_CHARS

$_GET = [
    'enabled' => 'true',
    'count' => '12',
    'code' => '0012',
];

$enabled = $globals->GET('enabled'); // true
$count = $globals->GET('count');     // 12
$code = $globals->GET('code');       // "0012"

Automatic filtering can be disabled persistently for individual reads:

$globals->filter(false);
$value = $globals->GET('value');

Use noFilter() when only the next read should bypass validation, sanitization, and type coercion:

$value = $globals->noFilter()->GET('value');

The configured UTF-8 conversion still applies to string values returned by noFilter().

Values outside a superglobal can use the same automatic behavior:

$filtered = $globals->autoFilterManualVar($value);

Explicit Filters

Invalid validation input is converted to the selected filter's return type. For example, an invalid integer becomes 0, while an invalid email address becomes an empty string.

Array filtering

Use array() before an explicit filter to apply that filter to each array value. The optional level determines the permitted nesting depth.

$_GET['emails'] = [
    'person@example.com',
    'not-an-email',
];

$emails = $globals->array()->email()->GET('emails');

// ['person@example.com', false]

Nested input can be handled by increasing the level:

$values = $globals->array(2)->int()->POST('values');

Selecting array() for scalar input returns an empty array.

JSON

JSON filters accept containers only. Scalar JSON values such as true, 42, and null are rejected to the appropriate empty container.

$array = $globals->json(true)->POST('payload');
$object = $globals->json(false)->POST('payload');

• json(true) returns an array or [].
• json(false) returns a stdClass instance or an empty stdClass.

UUIDs

$uuid = $globals->uuid()->GET('id');
$bytes = $globals->uuid(true)->GET('id');

Invalid UUID strings return '' in string mode and null in byte mode.

Callbacks

$length = $globals
    ->callback(static fn (string $value): int => strlen($value))
    ->POST('name');

Callbacks may return any type. They can also be combined with array() to process every value in an input array.

Defaults and UTF-8 Handling

Enable filter-specific defaults for missing values:

$globals->defaults(true);

$page = $globals->int()->GET('missing');       // 0
$emails = $globals->array()->GET('missing');   // []
$date = $globals->date()->GET('missing');      // "0000-00-00"

UTF-8 conversion is enabled by default for filtered strings. It can be disabled when handling binary or otherwise encoding-sensitive values:

$globals->utf8(false);

Security

Filtering and sanitization do not make input universally safe. Continue to use prepared statements for database queries, context-appropriate escaping for HTML and JavaScript output, and application-level validation and authorization.

Development

Run the complete local quality suite with:

./dc up -d
./dc exec php composer check

The suite includes PHP syntax checks and PHPUnit tests. GitHub Actions runs it against every supported PHP version.

Releases

Releases use bare semantic-version tags such as 4.0.6. The local release tooling updates VERSION and the value below ### Version, and prevents tagging until a matching release section exists in CHANGELOG.md.

Pushing the tag runs the complete PHP quality matrix. After it passes, GitHub Actions creates the GitHub Release from that version's changelog section. Packagist continues to receive the tag through the repository's existing GitHub integration. Release tags must not be moved or reused.

Acknowledgements

This project was originally derived from Coercive/Globals and has since evolved as an independently maintained implementation.

License

GCWorld Globals is open-source software licensed under the terms in LICENSE.txt.