stellarwp/superglobals

A library that handles access to superglobals.

1.3.0 2024-06-26 14:12 UTC

Requires

• stellarwp/arrays: ^1.2

Requires (Dev)

• phpunit/phpunit: <10.0
• symfony/event-dispatcher-contracts: ^2.5.1
• symfony/string: ^5.4
• szepeviktor/phpstan-wordpress: ^1.1

MIT

• StellarWP
• Matthew Batchelder

README

A library that handles access to superglobals.

Why create a library for this? WordPress .org does not like plugins to directly access superglobals, so this library was created to handle this in a consistent and safe way and can be included as a composer dependency.

Table of Contents

• Installation
• Usage
  • SuperGlobals::get_get_var( $var, $default = null )
  • SuperGlobals::get_post_var( $var, $default = null )
  • SuperGlobals::get_raw_superglobal( string $superglobal )
  • SuperGlobals::get_sanitized_superglobal( string $superglobal )
  • SuperGlobals::get_server_var( $var, $default = null )
  • SuperGlobals::get_var( $var, $default = null )
  • SuperGlobals::sanitize_deep( &$value )

Installation

It's recommended that you install SuperGlobals as a project dependency via Composer:

composer require stellarwp/superglobals

We actually recommend that this library gets included in your project using Strauss.

Luckily, adding Strauss to your composer.json is only slightly more complicated than adding a typical dependency, so checkout our strauss docs.

An important note on namespaces:

The docs will in this repo all use StellarWP\SuperGlobals as the base namespace, however, if you are using Strauss to prefix namespaces in your project, you will need to adapt the namespaces accordingly. (Example: Boom\Shakalaka\StellarWP\SuperGlobals)

Usage

SuperGlobals::get_get_var( $var, $default = null )

Get a $_GET value and recursively sanitize it using SuperGlobals::sanitize_deep().

Example

use StellarWP\SuperGlobals\SuperGlobals;

// Get $_GET['post_id']
$var = SuperGlobals::get_get_var( 'post_id' );

// Provide a default value if the variable is not set.
$var = SuperGlobals::get_get_var( 'post_id', 12 );

SuperGlobals::get_post_var( $var, $default = null )

Get a $_POST value and recursively sanitize it using SuperGlobals::sanitize_deep().

Example

use StellarWP\SuperGlobals\SuperGlobals;

// Get $_POST['post_id']
$var = SuperGlobals::get_post_var( 'post_id' );

// Provide a default value if the variable is not set.
$var = SuperGlobals::get_post_var( 'post_id', 12 );

SuperGlobals::get_raw_superglobal( string $superglobal )

Gets the requested superglobal variable. Options are ENV, GET, POST, REQUEST, or SERVER.

Example

use StellarWP\SuperGlobals\SuperGlobals;

// Get $_ENV
$env     = SuperGlobals::get_raw_superglobal( 'ENV' );

// Get $_GET
$get     = SuperGlobals::get_raw_superglobal( 'GET' );

// Get $_POST
$post    = SuperGlobals::get_raw_superglobal( 'POST' );

// Get $_REQUEST
$request = SuperGlobals::get_raw_superglobal( 'REQUEST' );

// Get $_SERVER
$server  = SuperGlobals::get_raw_superglobal( 'SERVER' );

SuperGlobals::get_sanitized_superglobal( string $superglobal )

Gets the requested superglobal variable, sanitized. Options are ENV, GET, POST, REQUEST, or SERVER.

Example

use StellarWP\SuperGlobals\SuperGlobals;

// Get $_ENV
$env     = SuperGlobals::get_sanitized_superglobal( 'ENV' );

// Get $_GET
$get     = SuperGlobals::get_sanitized_superglobal( 'GET' );

// Get $_POST
$post    = SuperGlobals::get_sanitized_superglobal( 'POST' );

// Get $_REQUEST
$request = SuperGlobals::get_sanitized_superglobal( 'REQUEST' );

// Get $_SERVER
$server  = SuperGlobals::get_sanitized_superglobal( 'SERVER' );

SuperGlobals::get_server_var( $var, $default = null )

Get a $_SERVER value and recursively sanitize it using SuperGlobals::sanitize_deep().

Example

use StellarWP\SuperGlobals\SuperGlobals;

// Get $_SERVER['REQUEST_URI']
$var = SuperGlobals::get_server_var( 'REQUEST_URI' );

// Provide a default value if the variable is not set.
$var = SuperGlobals::get_server_var( 'REQUEST_URI', 'http://example.com' );

SuperGlobals::get_var( $var, $default = null )

Gets a value from $_REQUEST, $_POST, or $_GET and recursively sanitizes it using SuperGlobals::sanitize_deep().

Example

use StellarWP\SuperGlobals\SuperGlobals;

// Get $_REQUEST['post_id'] or $_POST['post_id'] or $_GET['post_id'], wherever it lives
$var = SuperGlobals::get_var( 'post_id' );

// Provide a default value if the variable is not set.
$var = SuperGlobals::get_var( 'post_id', 12 );

SuperGlobals::sanitize_deep( &$value )

Sanitizes a value recursively using appropriate sanitization functions depending on the type of the value.

Example

use StellarWP\SuperGlobals\SuperGlobals;

$var = SuperGlobals::sanitize_deep( $some_var );