From 2f61ea6b9f3e3d6f6287f586499263728d2e0f69 Mon Sep 17 00:00:00 2001
From: Matthew Batchelder <borkweb@gmail.com>
Date: Wed, 22 May 2024 17:47:28 -0400
Subject: [PATCH] Initial commit

---
 .editorconfig                |  18 +++++
 .gitignore                   |  28 +++++++
 LICENSE                      |   2 +-
 README.md                    | 110 +++++++++++++++++++++++++-
 composer.json                |  56 +++++++++++++
 phpstan.neon.dist            |  29 +++++++
 src/SuperGlobals/Request.php | 147 +++++++++++++++++++++++++++++++++++
 7 files changed, 387 insertions(+), 3 deletions(-)
 create mode 100644 .editorconfig
 create mode 100644 .gitignore
 create mode 100644 composer.json
 create mode 100644 phpstan.neon.dist
 create mode 100644 src/SuperGlobals/Request.php

diff --git a/.editorconfig b/.editorconfig
new file mode 100644
index 0000000..d240d02
--- /dev/null
+++ b/.editorconfig
@@ -0,0 +1,18 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+indent_style = tab
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[*.md]
+trim_trailing_whitespace = true
+
+[*.{neon,neon.dist}]
+indent_style = tab
+
+[**.{jshintrc,json,scss-lint,yml}]
+indent_style = space
+indent_size = 2
\ No newline at end of file
diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..da7942b
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,28 @@
+composer.lock
+files/
+repo/
+vendor/
+tests/_support/_generated
+bin/*.phar
+
+# Dev tools
+.buildpath
+*.iml
+.project
+.idea/
+.vscode/
+
+# Third party dependencies
+vendor/
+
+# Tests
+codeception.yml
+tests/_output/*
+tests/*.suite.yml
+!tests/_data/dump.sql
+!tests/_data/pue.sql
+!tests/_data/pue-files
+!tests/_pue-files/*.zip
+tests/*.pem
+tests/*.cert
+tests/*.key
diff --git a/LICENSE b/LICENSE
index 11d43b4..28e1e52 100644
--- a/LICENSE
+++ b/LICENSE
@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2024 StellarWP
+Copyright (c) 2023 StellarWP
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
diff --git a/README.md b/README.md
index 600f915..8c023fa 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,108 @@
-# superglobals
-A small library that handles access to superglobals
+# StellarWP SuperGlobals
+
+A library that handles access to superglobals.
+
+## Table of Contents
+
+* [Installation](#installation)
+* [Usage](#usage)
+  * [`Request::get_get_var( $var, $default = null )`](#get_get_var-var-default-null)
+  * [`Request::get_post_var( $var, $default = null )`](#get_post_var-var-default-null)
+  * [`Request::get_server_var( $var, $default = null )`](#get_server_var-var-default-null)
+  * [`Request::get_var( $var, $default = null )`](#get_var-var-default-null)
+  * [`Request::sanitize_deep( &$value )`](#sanitize_deep-value)
+
+## Installation
+
+It's recommended that you install SuperGlobals as a project dependency via [Composer](https://getcomposer.org/):
+
+```bash
+composer require stellarwp/superglobals
+```
+
+> We _actually_ recommend that this library gets included in your project using [Strauss](https://github.com/BrianHenryIE/strauss).
+>
+> Luckily, adding Strauss to your `composer.json` is only slightly more complicated than adding a typical dependency, so checkout our [strauss docs](https://github.com/stellarwp/global-docs/blob/main/docs/strauss-setup.md).
+
+**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](#strauss)
+> to prefix namespaces in your project, you will need to adapt the namespaces accordingly. (Example: `Boom\Shakalaka\StellarWP\SuperGlobals`)
+
+## Usage
+
+### `Request::get_get_var( $var, $default = null )`
+
+Get a `$_GET` value and recursively sanitize it using `Request::sanitize_deep()`.
+
+#### Example
+
+```php
+use StellarWP\SuperGlobals\Request;
+
+// Get $_GET['post_id']
+$var = Request::get_get_var( 'post_id' );
+
+// Provide a default value if the variable is not set.
+$var = Request::get_get_var( 'post_id', 12 );
+```
+
+### `Request::get_post_var( $var, $default = null )`
+
+Get a `$_POST` value and recursively sanitize it using `Request::sanitize_deep()`.
+
+#### Example
+
+```php
+use StellarWP\SuperGlobals\Request;
+
+// Get $_POST['post_id']
+$var = Request::get_post_var( 'post_id' );
+
+// Provide a default value if the variable is not set.
+$var = Request::get_post_var( 'post_id', 12 );
+```
+
+### `Request::get_server_var( $var, $default = null )`
+
+Get a `$_SERVER` value and recursively sanitize it using `Request::sanitize_deep()`.
+
+#### Example
+
+```php
+use StellarWP\SuperGlobals\Request;
+
+// Get $_SERVER['REQUEST_URI']
+$var = Request::get_server_var( 'REQUEST_URI' );
+
+// Provide a default value if the variable is not set.
+$var = Request::get_server_var( 'REQUEST_URI', 'http://example.com' );
+```
+
+### `Request::get_var( $var, $default = null )`
+
+Gets a value from `$_REQUEST`, `$_POST`, or `$_GET` and recursively sanitizes it using `Request::sanitize_deep()`.
+
+#### Example
+
+```php
+use StellarWP\SuperGlobals\Request;
+
+// Get $_REQUEST['post_id'] or $_POST['post_id'] or $_GET['post_id'], wherever it lives
+$var = Request::get_var( 'post_id' );
+
+// Provide a default value if the variable is not set.
+$var = Request::get_var( 'post_id', 12 );
+```
+
+### `Request::sanitize_deep( &$value )`
+
+Sanitizes a value recursively using appropriate sanitization functions depending on the type of the value.
+
+#### Example
+
+```php
+use StellarWP\SuperGlobals\Request;
+
+$var = Request::sanitize_deep( $some_var );
+```
diff --git a/composer.json b/composer.json
new file mode 100644
index 0000000..db5acd6
--- /dev/null
+++ b/composer.json
@@ -0,0 +1,56 @@
+{
+  "name": "stellarwp/superglobals",
+  "description": "A library that handles access to superglobals.",
+  "type": "library",
+  "license": "MIT",
+  "platform": {
+    "php": "7.4"
+  },
+  "autoload": {
+    "psr-4": {
+      "StellarWP\\SuperGlobals\\": "src/SuperGlobals/"
+    }
+  },
+  "autoload-dev": {
+    "psr-4": {
+      "StellarWP\\SuperGlobals\\Tests\\": "tests/_support/Helper/"
+    }
+  },
+  "authors": [
+    {
+      "name": "StellarWP",
+      "email": "dev@stellarwp.com"
+    },
+    {
+      "name": "Matthew Batchelder",
+      "email": "matt.batchelder@stellarwp.com"
+    }
+  ],
+  "minimum-stability": "stable",
+  "require": {
+    "stellarwp/arrays": "^1.2"
+  },
+  "require-dev": {
+    "codeception/module-asserts": "^1.0",
+    "codeception/module-cli": "^1.0",
+    "codeception/module-db": "^1.0",
+    "codeception/module-filesystem": "^1.0",
+    "codeception/module-phpbrowser": "^1.0",
+    "codeception/module-rest": "^1.0",
+    "codeception/module-webdriver": "^1.0",
+    "codeception/util-universalframework": "^1.0",
+    "lucatume/wp-browser": "^3.0.14",
+    "phpunit/phpunit": "~6.0",
+    "szepeviktor/phpstan-wordpress": "^1.1",
+    "symfony/event-dispatcher-contracts": "^2.5.1",
+    "symfony/string": "^5.4"
+  },
+  "scripts": {
+    "test:analysis": [
+      "phpstan analyse -c phpstan.neon.dist --memory-limit=512M"
+    ]
+  },
+  "scripts-descriptions": {
+    "test:analysis": "Run static code analysis."
+  }
+}
diff --git a/phpstan.neon.dist b/phpstan.neon.dist
new file mode 100644
index 0000000..0346562
--- /dev/null
+++ b/phpstan.neon.dist
@@ -0,0 +1,29 @@
+# Configuration for PHPStan
+# https://phpstan.org/config-reference
+
+includes:
+	# @see https://github.com/phpstan/phpstan-src/blob/master/conf/bleedingEdge.neon
+	- phar://phpstan.phar/conf/bleedingEdge.neon
+	# Include this extension
+	- vendor/szepeviktor/phpstan-wordpress/extension.neon
+
+parameters:
+	parallel:
+		jobSize: 10
+		maximumNumberOfProcesses: 32
+		minimumNumberOfJobsPerProcess: 2
+	level: 5
+	inferPrivatePropertyTypeFromConstructor: true
+	reportUnmatchedIgnoredErrors: false
+	checkGenericClassInNonGenericObjectType: false
+	treatPhpDocTypesAsCertain: false
+
+	# Paths to be analyzed.
+	paths:
+		- %currentWorkingDirectory%/src
+
+	ignoreErrors:
+		# Uses func_get_args()
+		- '#^Function add_query_arg invoked with [123] parameters?, 0 required\.$#'
+		# Uses func_get_args()
+		- '#^Function apply_filters(_ref_array)? invoked with [34567] parameters, 2 required\.$#'
diff --git a/src/SuperGlobals/Request.php b/src/SuperGlobals/Request.php
new file mode 100644
index 0000000..afc8c3d
--- /dev/null
+++ b/src/SuperGlobals/Request.php
@@ -0,0 +1,147 @@
+<?php
+
+namespace StellarWP\SuperGlobals;
+
+use StellarWP\Arrays\Arr;
+
+class Request {
+	/**
+	 * Grab sanitized _SERVER variable.
+	 *
+	 * @since 1.0.0
+	 *
+	 * @see   Arr::get()
+	 *
+	 * @param string|array $var
+	 * @param mixed        $default
+	 *
+	 * @return mixed
+	 */
+	public static function get_server_var( $var, $default = null ) {
+		$data = [];
+
+		// Prevent a slew of warnings every time we call this.
+		if ( ! empty( $_SERVER ) ) {
+			$data[] = (array) $_SERVER;
+		}
+
+		if ( empty( $data ) ) {
+			return $default;
+		}
+
+		$unsafe = Arr::get_in_any( $data, $var, $default );
+		return static::sanitize_deep( $unsafe );
+	}
+
+	/**
+	 * Gets a value from `$_GET`.
+	 *
+	 * @since 1.0.0
+	 *
+	 * @see   Arr::get()
+	 *
+	 * @param string $var
+	 * @param mixed $default
+	 *
+	 * @return mixed
+	 */
+	public static function get_get_var( string $var, $default = null ) {
+		$unsafe = Arr::get( (array) $_GET, $var, $default );
+		return static::sanitize_deep( $unsafe );
+	}
+
+	/**
+	 * Gets a value from `$_POST`.
+	 *
+	 * @since 1.0.0
+	 *
+	 * @see   Arr::get()
+	 *
+	 * @param string $var
+	 * @param mixed  $default
+	 *
+	 * @return mixed
+	 */
+	public static function get_post_var( string $var, $default = null ) {
+		$unsafe = Arr::get( (array) $_POST, $var, $default );
+		return static::sanitize_deep( $unsafe );
+	}
+
+	/**
+	 * Tests to see if the requested variable is set either as a post field or as a URL
+	 * param and returns the value if so.
+	 *
+	 * Post data takes priority over fields passed in the URL query. If the field is not
+	 * set then $default (null unless a different value is specified) will be returned.
+	 *
+	 * The variable being tested for can be an array if you wish to find a nested value.
+	 *
+	 * @since 1.0.0
+	 *
+	 * @see   Arr::get()
+	 *
+	 * @param string|array $var
+	 * @param mixed        $default
+	 *
+	 * @return mixed
+	 */
+	public static function get_var( $var, $default = null ) {
+		$requests = [];
+
+		// Prevent a slew of warnings every time we call this.
+		if ( ! empty( $_REQUEST ) ) {
+			$requests[] = (array) $_REQUEST;
+		}
+
+		if ( ! empty( $_POST ) ) {
+			$requests[] = (array) $_POST;
+		}
+
+		if ( ! empty( $_GET ) ) {
+			$requests[] = (array) $_GET;
+		}
+
+		if ( empty( $requests ) ) {
+			return $default;
+		}
+
+		$unsafe = Arr::get_in_any( $requests, $var, $default );
+		return static::sanitize_deep( $unsafe );
+	}
+
+	/**
+	 * Sanitizes a value according to its type.
+	 *
+	 * The function will recursively sanitize array values.
+	 *
+	 * @since 1.0.0
+	 *
+	 * @param mixed $value The value, or values, to sanitize.
+	 *
+	 * @return mixed|null Either the sanitized version of the value, or `null` if the value is not a string, number or
+	 *                    array.
+	 */
+	public static function sanitize_deep( &$value ) {
+		if ( is_bool( $value ) ) {
+			return $value;
+		}
+		if ( is_string( $value ) ) {
+			$value = htmlspecialchars( $value );
+			return $value;
+		}
+		if ( is_int( $value ) ) {
+			$value = filter_var( $value, FILTER_VALIDATE_INT );
+			return $value;
+		}
+		if ( is_float( $value ) ) {
+			$value = filter_var( $value, FILTER_VALIDATE_FLOAT );
+			return $value;
+		}
+		if ( is_array( $value ) ) {
+			array_walk( $value, [ __CLASS__, 'sanitize_deep' ] );
+			return $value;
+		}
+
+		return null;
+	}
+}