Sophia/avatar-privacy
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

first commit

Browse Source
This commit is contained in:
Sophia Atkinson
2023-09-01 00:37:57 -07:00
commit 9caab8ce68
602 changed files with 33485 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

319
vendor-scoped/level-2/dice/Dice.php Normal file
View File

@ -0,0 +1,319 @@
<?php
/* @description Dice - A minimal Dependency Injection Container for PHP
* @author Tom Butler tom@r.je
* @copyright 2012-2020 Tom Butler <tom@r.je> | https://r.je/dice
* @license http://www.opensource.org/licenses/bsd-license.php BSD License
* @version 4.0 */
namespace Avatar_Privacy\Vendor\Dice;
class Dice
{
const CONSTANT = 'Dice::CONSTANT';
const GLOBAL = 'Dice::GLOBAL';
const INSTANCE = 'Dice::INSTANCE';
const CHAIN_CALL = 'Dice::CHAIN_CALL';
const SELF = 'Dice::SELF';
/**
* @var array $rules Rules which have been set using addRule()
*/
private $rules = [];
/**
* @var array $cache A cache of closures based on class name so each class is only reflected once
*/
private $cache = [];
/**
* @var array $instances Stores any instances marked as 'shared' so create() can return the same instance
*/
private $instances = [];
/**
* Add a rule $rule to the class $name
* @param string $name The name of the class to add the rule for
* @param array $rule The container can be fully configured using rules provided by associative arrays. See {@link https://r.je/dice.html#example3} for a description of the rules.
*/
public function addRule(string $name, array $rule) : self
{
$dice = clone $this;
$this->addRuleTo($dice, $name, $rule);
return $dice;
}
/**
* Add rules as array. Useful for JSON loading $dice->addRules(json_decode(file_get_contents('foo.json'));
* @param array Rules in a single array [name => $rule] format
*/
public function addRules($rules) : self
{
if (\is_string($rules)) {
$rules = \json_decode(\file_get_contents($rules), \true);
}
$dice = clone $this;
foreach ($rules as $name => $rule) {
$this->addRuleTo($dice, $name, $rule);
}
return $dice;
}
private function addRuleTo(Dice $dice, string $name, array $rule)
{
if (isset($rule['instanceOf']) && (!\array_key_exists('inherit', $rule) || $rule['inherit'] === \true)) {
$rule = \array_replace_recursive($dice->getRule($rule['instanceOf']), $rule);
}
//Allow substitutions rules to be defined with a leading a slash
if (isset($rule['substitutions'])) {
foreach ($rule['substitutions'] as $key => $value) {
$rule['substitutions'][\ltrim($key, '\\')] = $value;
}
}
//Clear any existing instance or cache for this class
unset($dice->instances[$name], $dice->cache[$name]);
$dice->rules[\ltrim(\strtolower($name), '\\')] = \array_replace_recursive($dice->getRule($name), $rule);
}
/**
* Returns the rule that will be applied to the class $name when calling create()
* @param string name The name of the class to get the rules for
* @return array The rules for the specified class
*/
public function getRule(string $name) : array
{
$lcName = \strtolower(\ltrim($name, '\\'));
if (isset($this->rules[$lcName])) {
return $this->rules[$lcName];
}
foreach ($this->rules as $key => $rule) {
// Find a rule which matches the class described in $name where:
if (empty($rule['instanceOf']) && $key !== '*' && \is_subclass_of($name, $key) && (!\array_key_exists('inherit', $rule) || $rule['inherit'] === \true)) {
// And that rule should be inherited to subclasses
return $rule;
}
}
// No rule has matched, return the default rule if it's set
return isset($this->rules['*']) ? $this->rules['*'] : [];
}
/**
* Returns a fully constructed object based on $name using $args and $share as constructor arguments if supplied
* @param string name The name of the class to instantiate
* @param array $args An array with any additional arguments to be passed into the constructor upon instantiation
* @param array $share a list of defined in shareInstances for objects higher up the object graph, should only be used internally
* @return object A fully constructed object based on the specified input arguments
*/
public function create(string $name, array $args = [], array $share = [])
{
// Is there a shared instance set? Return it. Better here than a closure for this, calling a closure is slower.
if (!empty($this->instances[$name])) {
return $this->instances[$name];
}
// Create a closure for creating the object if there isn't one already
if (empty($this->cache[$name])) {
$this->cache[$name] = $this->getClosure(\ltrim($name, '\\'), $this->getRule($name));
}
// Call the cached closure which will return a fully constructed object of type $name
return $this->cache[$name]($args, $share);
}
/**
* Returns a closure for creating object $name based on $rule, caching the reflection object for later use
* @param string $name the Name of the class to get the closure for
* @param array $rule The container can be fully configured using rules provided by associative arrays. See {@link https://r.je/dice.html#example3} for a description of the rules.
* @return callable A closure
*/
private function getClosure(string $name, array $rule)
{
// Reflect the class and constructor, this should only ever be done once per class and get cached
$class = new \ReflectionClass(isset($rule['instanceOf']) ? $rule['instanceOf'] : $name);
$constructor = $class->getConstructor();
// Create parameter generating function in order to cache reflection on the parameters. This way $reflect->getParameters() only ever gets called once
$params = $constructor ? $this->getParams($constructor, $rule) : null;
//PHP throws a fatal error rather than an exception when trying to instantiate an interface, detect it and throw an exception instead
if ($class->isInterface()) {
$closure = function () {
throw new \InvalidArgumentException('Cannot instantiate interface');
};
} else {
if ($params) {
$closure = function (array $args, array $share) use($class, $params) {
// This class has depenencies, call the $params closure to generate them based on $args and $share
return new $class->name(...$params($args, $share));
};
} else {
$closure = function () use($class) {
// No constructor arguments, just instantiate the class
return new $class->name();
};
}
}
if (!empty($rule['shared'])) {
$closure = function (array $args, array $share) use($class, $name, $constructor, $params, $closure) {
//Internal classes may not be able to be constructed without calling the constructor and will not suffer from #7, construct them normally.
if ($class->isInternal()) {
$this->instances[$class->name] = $this->instances['\\' . $class->name] = $closure($args, $share);
} else {
//Otherwise, create the class without calling the constructor (and write to \$name and $name, see issue #68)
$this->instances[$name] = $this->instances['\\' . $name] = $class->newInstanceWithoutConstructor();
// Now call this constructor after constructing all the dependencies. This avoids problems with cyclic references (issue #7)
if ($constructor) {
$constructor->invokeArgs($this->instances[$name], $params($args, $share));
}
}
return $this->instances[$name];
};
}
// If there are shared instances, create them and merge them with shared instances higher up the object graph
if (isset($rule['shareInstances'])) {
$closure = function (array $args, array $share) use($closure, $rule) {
foreach ($rule['shareInstances'] as $instance) {
$share[] = $this->create($instance, [], $share);
}
return $closure($args, $share);
};
}
// When $rule['call'] is set, wrap the closure in another closure which will call the required methods after constructing the object
// By putting this in a closure, the loop is never executed unless call is actually set
return isset($rule['call']) ? function (array $args, array $share) use($closure, $class, $rule, $name) {
// Construct the object using the original closure
$object = $closure($args, $share);
foreach ($rule['call'] as $call) {
// Generate the method arguments using getParams() and call the returned closure
$params = $this->getParams($class->getMethod($call[0]), ['shareInstances' => isset($rule['shareInstances']) ? $rule['shareInstances'] : []])($this->expand(isset($call[1]) ? $call[1] : []), $share);
$return = $object->{$call[0]}(...$params);
if (isset($call[2])) {
if ($call[2] === self::CHAIN_CALL) {
if (!empty($rule['shared'])) {
$this->instances[$name] = $return;
}
if (\is_object($return)) {
$class = new \ReflectionClass(\get_class($return));
}
$object = $return;
} else {
if (\is_callable($call[2])) {
\call_user_func($call[2], $return);
}
}
}
}
return $object;
} : $closure;
}
/**
* Looks for Dice::INSTANCE, Dice::GLOBAL or Dice::CONSTANT array keys in $param and when found returns an object based on the value see {@link https:// r.je/dice.html#example3-1}
* @param mixed $param Either a string or an array,
* @param array $share Array of instances from 'shareInstances', required for calls to `create`
* @param bool $createFromString
* @return mixed
*/
private function expand($param, array $share = [], bool $createFromString = \false)
{
if (\is_array($param)) {
//if a rule specifies Dice::INSTANCE, look up the relevant instance
if (isset($param[self::INSTANCE])) {
if ($param[self::INSTANCE] === self::SELF) {
return $this;
}
//Check for 'params' which allows parameters to be sent to the instance when it's created
//Either as a callback method or to the constructor of the instance
$args = isset($param['params']) ? $this->expand($param['params']) : [];
//Support Dice::INSTANCE by creating/fetching the specified instance
if (\is_array($param[self::INSTANCE])) {
$param[self::INSTANCE][0] = $this->expand($param[self::INSTANCE][0], $share, \true);
}
if (\is_callable($param[self::INSTANCE])) {
return \call_user_func($param[self::INSTANCE], ...$args);
} else {
return $this->create($param[self::INSTANCE], \array_merge($args, $share));
}
} else {
if (isset($param[self::GLOBAL])) {
return $GLOBALS[$param[self::GLOBAL]];
} else {
if (isset($param[self::CONSTANT])) {
return \constant($param[self::CONSTANT]);
} else {
foreach ($param as $name => $value) {
$param[$name] = $this->expand($value, $share);
}
}
}
}
}
return \is_string($param) && $createFromString ? $this->create($param) : $param;
}
/**
* Looks through the array $search for any object which can be used to fulfil $param
The original array $search is modifed so must be passed by reference.
*/
private function matchParam(\ReflectionParameter $param, $class, array &$search)
{
foreach ($search as $i => $arg) {
if ($class && ($arg instanceof $class || $arg === null && $param->allowsNull())) {
// The argument matched, return it and remove it from $search so it won't wrongly match another parameter
return \array_splice($search, $i, 1)[0];
}
}
return \false;
}
/**
* Returns a closure that generates arguments for $method based on $rule and any $args passed into the closure
* @param object $method An instance of ReflectionMethod (see: {@link http:// php.net/manual/en/class.reflectionmethod.php})
* @param array $rule The container can be fully configured using rules provided by associative arrays. See {@link https://r.je/dice.html#example3} for a description of the rules.
* @return callable A closure that uses the cached information to generate the arguments for the method
*/
private function getParams(\ReflectionMethod $method, array $rule)
{
// Cache some information about the parameter in $paramInfo so (slow) reflection isn't needed every time
$paramInfo = [];
foreach ($method->getParameters() as $param) {
$type = $param->getType();
$class = $type instanceof \ReflectionNamedType && !$type->isBuiltIn() ? $type->getName() : null;
$paramInfo[] = [$class, $param, isset($rule['substitutions']) && \array_key_exists($class, $rule['substitutions'])];
}
// Return a closure that uses the cached information to generate the arguments for the method
return function (array $args, array $share = []) use($paramInfo, $rule) {
// If the rule has construtParams set, construct any classes reference and use them as $args
if (isset($rule['constructParams'])) {
$args = \array_merge($args, $this->expand($rule['constructParams'], $share));
}
// Array of matched parameters
$parameters = [];
// Fnd a value for each method argument
foreach ($paramInfo as list($class, $param, $sub)) {
// Loop through $args and see whether or not each value can match the current parameter based on type hint
if ($args && ($match = $this->matchParam($param, $class, $args)) !== \false) {
$parameters[] = $match;
} else {
if (($copy = $share) && ($match = $this->matchParam($param, $class, $copy)) !== \false) {
$parameters[] = $match;
} else {
if ($class) {
try {
if ($sub) {
$parameters[] = $this->expand($rule['substitutions'][$class], $share, \true);
} else {
$parameters[] = !$param->allowsNull() ? $this->create($class, [], $share) : null;
}
} catch (\InvalidArgumentException $e) {
}
} else {
if ($args && $param->getType()) {
for ($i = 0; $i < \count($args); $i++) {
if (\call_user_func('is_' . $param->getType()->getName(), $args[$i])) {
$parameters[] = \array_splice($args, $i, 1)[0];
break;
}
}
} else {
if ($args) {
$parameters[] = $this->expand(\array_shift($args));
} else {
if ($param->isVariadic()) {
$parameters = \array_merge($parameters, $args);
} else {
$parameters[] = $param->isDefaultValueAvailable() ? $param->getDefaultValue() : null;
}
}
}
}
}
}
}
return $parameters;
};
}
}

365
vendor-scoped/level-2/dice/README.md Normal file
View File

@ -0,0 +1,365 @@
[Dice PHP Dependency Injection Container](https://r.je/dice.html)
======================================
Dice is a minimalist Dependency Injection Container for PHP with a focus on being lightweight and fast as well as requiring as little configuration as possible.
Project Goals
-------------
1) To be lightweight and not a huge library with dozens of files (Dice is a single 100 line class) yet support all features (and more) offered by much more complex containers
2) To "just work". Basic functionality should work with zero configuration
3) Where configuration is required, it should be as minimal and reusable as possible as well as easy to use.
4) Speed! (See [the section on performance](#performance))
Installation
------------
Just include the lightweight `Dice.php` in your project and it's usable without any further configuration:
Simple example:
```php
<?php
class A {
public $b;
public function __construct(B $b) {
$this->b = $b;
}
}
class B {
}
require_once 'Dice.php';
$dice = new \Dice\Dice;
$a = $dice->create('A');
var_dump($a->b); //B object
?>
```
Full Documentation
------------------
For complete documentation please see the [Dice PHP Dependency Injection container home page](https://r.je/dice.html)
PHP version compatibility
-------------------------
Dice is compatible with PHP 7.0 and up, there are archived versions of Dice which support PHP 5.6 however this is no longer maintanied.
Performance
-----------
Dice uses reflection which is often wrongly labelled "slow". Reflection is considerably faster than loading and parsing a configuration file. There are a set of benchmarks [here](https://rawgit.com/TomBZombie/php-dependency-injection-benchmarks/master/test1-5_results.html) and [here](https://rawgit.com/TomBZombie/php-dependency-injection-benchmarks/master/test6_results.html) (To download the benchmark tool yourself see [this repository](https://github.com/TomBZombie/php-dependency-injection-benchmarks)) and Dice is faster than the others in most cases.
In the real world test ([test 6](https://rawgit.com/TomBZombie/php-dependency-injection-benchmarks/master/test6_results.html)) Dice is neck-and-neck with Pimple (which requires writing an awful lot of configuration code) and although Symfony\DependencyInjection is faster at creating objects, it has a larger overhead and you need to create over 500 objects on each page load until it becomes faster than Dice. The same is true of Phalcon, the overhead of loading the Phalcon extension means that unless you're creating well over a thousand objects per HTTP request, the overhead is not worthwhile.
Credits
------------
Originally developed by Tom Butler (@TomBZombie), with many thanks to daniel-meister (@daniel-meister), Garrett W. (@garrettw), maxwilms (@maxwilms) for bug fixes, suggestions and improvements.
Updates
------------
### 15/11/2018 4.0 Release - Backwards incompatible
Dice is now immutable and has better support for other immutable objects.
**New Features**
#### 1. Dice is Immutable
This avoids [issues surrounding mutability](https://www.yegor256.com/2014/06/09/objects-should-be-immutable.html) where a Dice instance is passed around the application and reconfigured. The only difference is that `addRules` and `addRule` return a new Dice instance with the updated rules rather than changing the state of the existing instance.
```php
// Pre-4.0 code:
$dice->addRule('PDO', ['shared' => true]);
$db = $dice->create('PDO');
// 4.0 code:
$dice = $dice->addRule('PDO', ['shared' => true]);
$db = $dice->create('PDO');
```
From a practical perspective in most cases just put `$dice = ` in front of any `$dice->addRule()` call and it will work as before.
#### 2. Support for Object Method Chaining
One feature some immutable objects have is they offer object chaining.
Consider the following Object:
```php
$httpRequest = new HTTPRequest();
$httpRequest = $httpRequest->url('http://example.org')->method('POST')->postdata('foo=bar');
```
It was not possible for Dice to consturuct the configured object in previous versions. As of 4.0 Dice supports chaining method call using the `call` rule and the `Dice::CHAIN_CALL` constant:
```php
$dice = $dice->addRule('HTTPRequest',
['call' => [
['url', ['http://example.org'], Dice::CHAIN_CALL],
['method', ['POST'], Dice::CHAIN_CALL ],
['postdata', ['foo=bar'], Dice::CHAIN_CALL]
]
]
);
```
Dice will replace the HTTPRequest object with the result of the chained call. This is also useful for factories:
```php
$dice = $dice->addRule('MyDatabase',
[
'instanceOf' => 'DatabaseFactory',
'call' => [
['get', ['Database'], Dice::CHAIN_CALL]
]
]
);
$database = $dice->create('MyDatabase');
//Equivalent of:
$factory = new DatabaseFactory();
$database = $factory->get('Database');
```
### 06/03/2018 3.0 Release - Backwards incompatible
**New Features**
#### 1. The JSON loader has been removed in favour of a new `addRules` method.
```php
$dice->addRules([
'\PDO' => [
'shared' => true
],
'Framework\Router' => [
'constructParams' => ['Foo', 'Bar']
]
]);
```
The purpose of this addition is to make the JSON loader redundant. Loading of rules from a JSON file can easily be achieved with the code:
```php
$dice->addRules(json_decode(file_get_contents('rules.json')));
```
#### 2. Better JSON file support: constants and superglobals
In order to improve support for rules being defined in external JSON files, constants and superglobals can now be passed into objects created by Dice.
For example, passing the `$_SERVER` superglobal into a router instance and calling PDO's `setAttribute` with `PDO::ATTR_ERRMODE` and `PDO::ERRMODE_EXCEPTION` can be achieved like this in a JSON file:
_rules.json_
```json
{
"Router": {
"constructParams": [
{"Dice::GLOBAL": "_SERVER"}
]
},
"PDO": {
"shared": true,
"constructParams": [
"mysql:dbname=testdb;host=127.0.0.1",
"dbuser",
"dbpass"
],
"call": [
[
"setAttribute",
[
{"Dice::CONSTANT": "PDO::ATTR_ERRMODE"},
{"Dice::CONSTANT": "PDO::ERRMODE_EXCEPTION"}
]
]
]
}
}
```
```php
$dice->addRules(json_decode(file_get_contents('rules.json')));
```
**Backwards incompatible changes**
1. Dice 3.0 requires PHP 7.0 or above, PHP 5.6 is no longer supported.
2. Dice no longer supports `'instance'` keys to signify instances. For example:
```php
$dice->addRule('ClassName', [
'constructParams' => ['instance' => '$NamedPDOInstance']
]);
```
As noted in issue #125 this made it impossible to pass an array to a constructor if the array had a key `'instance'`. Instead, the new `\Dice\Dice::INSTANCE` constant should be used:
```php
$dice->addRule('ClassName', [
'constructParams' => [\Dice\Dice::INSTANCE => '$NamedPDOInstance']
]);
```
_to make the constant shorter to type out, you can `use \Dice\Dice;` and reference `Dice::INSTANCE`_
10/06/2016
** Backwards incompatible change **
Based on [Issue 110](https://github.com/Level-2/Dice/pull/110) named instances using `instanceOf` will now inherit the rules applied to the class they are instances of:
```php
$rule = [];
$rule['shared'] = true;
$dice->addRule('MyClass', $rule);
$rule = [];
$rule['instanceOf'] = 'MyClass';
$rule['constructParams'] = ['Foo', 'Bar'];
$dice->addRule('$MyNamedInstance', $rule);
```
`$dice->create('$MyNamedInstance')` will now create a class following the rules applied to both `MyClass` and `$MyNamedInstance` so the instance will be shared.
Previously only the rules applied to the named instance would be used.
To restore the old behaviour, set `inherit` to `false` on the named instance:
```php
$rule = [];
$rule['shared'] = true;
$dice->addRule('MyClass', $rule);
$rule = [];
$rule['instanceOf'] = 'MyClass';
$rule['constructParams'] = ['Foo', 'Bar'];
//Prevent the named instance inheriting rules from the class named in `instanceOf`:
$rule['inherit'] = false;
$dice->addRule('$MyNamedInstance', $rule);
```
29/10/2014
* Based on [Issue #15](https://github.com/TomBZombie/Dice/issues/15), Dice will now only call closures if they are wrapped in \Dice\Instance. **PLEASE NOTE: THIS IS BACKWARDS INCOMPATIBLE **.
Previously Dice ran closures that were passed as substitutions, constructParams and when calling methods:
```php
$rule->substitutions['A'] = function() {
return new A;
};
$rule->call[] = ['someMethod', function() {
// '2' will be provided as the first argument when someMethod is called
return 2;
}];
$rule->constructParams[] = function() {
//'abc' will be providedas the first constructor parameter
return 'abc';
};
```
This behaviour has changed as it makes it impossible to provide a closure as a construct parameter or when calling a method because the closure was always called and executed.
To overcome this, Dice will now only call a closures if they're wrapped in \Dice\Instance:
```php
$rule->substitutions['A'] = ['instance' => function() {
return new A;
}];
$rule->call[] = ['someMethod', ['instance' => function() {
// '2' will be provided as the first argument when someMethod is called
return 2;
}]]);
$rule->constructParams[] = ['instance' => function() { {
//'abc' will be providedas the first constructor parameter
return 'abc';
}]);
```
04/09/2014
* Pushed PHP5.6 branch live. This is slightly more efficient using PHP5.6 features. For PHP5.4-PHP5.5 please see the relevant branch. This version will be maintained until PHP5.6 is more widespread.
26/08/2014
* Added PHP5.6 branch. Tidied up code by using PHP5.6 features. This will be moved to master when PHP5.6 is released
28/06/2014
* Greatly improved efficienty. Dice is now the fastest Dependency Injection Container for PHP!
06/06/2014
* Added support for cyclic references ( https://github.com/TomBZombie/Dice/issues/7 ). Please note this is poor design but this fix will stop the infinite loop this design creates.
27/03/2014
* Removed assign() method as this duplicated functionality available using $rule->shared
* Removed $callback argument in $dice->create() as the only real use for this feature can be better achieved using $rule->shareInstances
* Tidied up code, removing unused/undocumented features. Dice is now even more lightweight and faster.
* Fixed a bug where when using $rule->call it would use the substitution rules from the constructor on each method called
* Updated [Dice documentation](https://r.je/dice.html) to use shorthand array syntax
01/03/2014
* Added test cases for the Xml Loader and Loader Callback classes
* Added a JSON loader + test case
* Added all test cases to a test suite
* Moved to PHP5.4 array syntax. A PHP5.3 compatible version is now available in the PHP5.3 branch.
* Fixed an issue where using named instances would trigger the autoloader with an invalid class name every time a class was created
28/02/2014
* Added basic namespace support. Documentation update will follow shortly. Also moved the XML loader into its own file, you'll need to include it separately if you're using it.
* Please note: CHANGES ARE NOT BACKWARDS COMPATIBLE. However they are easily fixed by doing the following find/replaces:
```php
new Dice => new \Dice\Dice
new DiceInstance => new \Dice\Instance
new DiceRule => new \Dice\Rule
```