dependabot-composer 0.111.16 → 0.111.17

data/helpers/vendor/composer/composer/doc/articles/http-basic-authentication.md

@@ -0,0 +1,59 @@
+<!--
+    tagline: Access privately hosted packages
+-->
+
+# HTTP basic authentication
+
+Your [Satis or Toran Proxy](handling-private-packages-with-satis.md) server
+could be secured with http basic authentication. In order to allow your project
+to have access to these packages you will have to tell composer how to
+authenticate with your credentials.
+
+The simplest way to provide your credentials is providing your set
+of credentials inline with the repository specification such as:
+
+```json
+{
+    "repositories": [
+        {
+            "type": "composer",
+            "url": "https://extremely:secret@repo.example.org"
+        }
+    ]
+}
+```
+
+This will basically teach composer how to authenticate automatically
+when reading packages from the provided composer repository.
+
+This does not work for everybody especially when you don't want to
+hard code your credentials into your composer.json. There is a second
+way to provide these details and it is via interaction. If you don't
+provide the authentication credentials composer will prompt you upon
+connection to enter the username and password.
+
+The third way if you want to pre-configure it is via an `auth.json` file
+located in your `COMPOSER_HOME` or besides your `composer.json`.
+
+The file should contain a set of hostnames followed each with their own
+username/password pairs, for example:
+
+```json
+{
+    "http-basic": {
+        "repo.example1.org": {
+            "username": "my-username1",
+            "password": "my-secret-password1"
+        },
+        "repo.example2.org": {
+            "username": "my-username2",
+            "password": "my-secret-password2"
+        }
+    }
+}
+```
+
+The main advantage of the auth.json file is that it can be gitignored so
+that every developer in your team can place their own credentials in there,
+which makes revocation of credentials much easier than if you all share the
+same.

data/helpers/vendor/composer/composer/doc/articles/plugins.md

@@ -0,0 +1,285 @@
+<!--
+    tagline: Modify and extend Composer's functionality
+-->
+
+# Setting up and using plugins
+
+## Synopsis
+
+You may wish to alter or expand Composer's functionality with your own. For
+example if your environment poses special requirements on the behaviour of
+Composer which do not apply to the majority of its users or if you wish to
+accomplish something with composer in a way that is not desired by most users.
+
+In these cases you could consider creating a plugin to handle your
+specific logic.
+
+## Creating a Plugin
+
+A plugin is a regular Composer package which ships its code as part of the
+package and may also depend on further packages.
+
+### Plugin Package
+
+The package file is the same as any other package file but with the following
+requirements:
+
+1. The [type][1] attribute must be `composer-plugin`.
+2. The [extra][2] attribute must contain an element `class` defining the
+   class name of the plugin (including namespace). If a package contains
+   multiple plugins, this can be array of class names.
+3. You must require the special package called `composer-plugin-api`
+   to define which Plugin API versions your plugin is compatible with.
+
+The required version of the `composer-plugin-api` follows the same [rules][7]
+as a normal package's.
+
+The current composer plugin API version is 1.1.0.
+
+An example of a valid plugin `composer.json` file (with the autoloading
+part omitted):
+
+```json
+{
+    "name": "my/plugin-package",
+    "type": "composer-plugin",
+    "require": {
+        "composer-plugin-api": "^1.1"
+    },
+    "extra": {
+        "class": "My\\Plugin"
+    }
+}
+```
+
+### Plugin Class
+
+Every plugin has to supply a class which implements the
+[`Composer\Plugin\PluginInterface`][3]. The `activate()` method of the plugin
+is called after the plugin is loaded and receives an instance of
+[`Composer\Composer`][4] as well as an instance of
+[`Composer\IO\IOInterface`][5]. Using these two objects all configuration can
+be read and all internal objects and state can be manipulated as desired.
+
+Example:
+
+```php
+<?php
+
+namespace phpDocumentor\Composer;
+
+use Composer\Composer;
+use Composer\IO\IOInterface;
+use Composer\Plugin\PluginInterface;
+
+class TemplateInstallerPlugin implements PluginInterface
+{
+    public function activate(Composer $composer, IOInterface $io)
+    {
+        $installer = new TemplateInstaller($io, $composer);
+        $composer->getInstallationManager()->addInstaller($installer);
+    }
+}
+```
+
+## Event Handler
+
+Furthermore plugins may implement the
+[`Composer\EventDispatcher\EventSubscriberInterface`][6] in order to have its
+event handlers automatically registered with the `EventDispatcher` when the
+plugin is loaded.
+
+To register a method to an event, implement the method `getSubscribedEvents()`
+and have it return an array. The array key must be the
+[event name](https://getcomposer.org/doc/articles/scripts.md#event-names)
+and the value is the name of the method in this class to be called.
+
+```php
+public static function getSubscribedEvents()
+{
+    return array(
+        'post-autoload-dump' => 'methodToBeCalled',
+        // ^ event name ^         ^ method name ^
+    );
+}
+```
+
+By default, the priority of an event handler is set to 0. The priority can be
+changed by attaching a tuple where the first value is the method name, as
+before, and the second value is an integer representing the priority.
+Higher integers represent higher priorities. Priority 2 is called before
+priority 1, etc.
+
+```php
+public static function getSubscribedEvents()
+{
+    return array(
+        // Will be called before events with priority 0
+        'post-autoload-dump' => array('methodToBeCalled', 1)
+    );
+}
+```
+
+If multiple methods should be called, then an array of tuples can be attached
+to each event. The tuples do not need to include the priority. If it is
+omitted, it will default to 0.
+
+```php
+public static function getSubscribedEvents()
+{
+    return array(
+        'post-autoload-dump' => array(
+            array('methodToBeCalled'      ), // Priority defaults to 0
+            array('someOtherMethodName', 1), // This fires first
+        )
+    );
+}
+```
+
+Here's a complete example:
+
+```php
+<?php
+
+namespace Naderman\Composer\AWS;
+
+use Composer\Composer;
+use Composer\EventDispatcher\EventSubscriberInterface;
+use Composer\IO\IOInterface;
+use Composer\Plugin\PluginInterface;
+use Composer\Plugin\PluginEvents;
+use Composer\Plugin\PreFileDownloadEvent;
+
+class AwsPlugin implements PluginInterface, EventSubscriberInterface
+{
+    protected $composer;
+    protected $io;
+
+    public function activate(Composer $composer, IOInterface $io)
+    {
+        $this->composer = $composer;
+        $this->io = $io;
+    }
+
+    public static function getSubscribedEvents()
+    {
+        return array(
+            PluginEvents::PRE_FILE_DOWNLOAD => array(
+                array('onPreFileDownload', 0)
+            ),
+        );
+    }
+
+    public function onPreFileDownload(PreFileDownloadEvent $event)
+    {
+        $protocol = parse_url($event->getProcessedUrl(), PHP_URL_SCHEME);
+
+        if ($protocol === 's3') {
+            $awsClient = new AwsClient($this->io, $this->composer->getConfig());
+            $s3RemoteFilesystem = new S3RemoteFilesystem($this->io, $event->getRemoteFilesystem()->getOptions(), $awsClient);
+            $event->setRemoteFilesystem($s3RemoteFilesystem);
+        }
+    }
+}
+```
+
+## Plugin capabilities
+
+Composer defines a standard set of capabilities which may be implemented by plugins.
+Their goal is to make the plugin ecosystem more stable as it reduces the need to mess
+with [`Composer\Composer`][4]'s internal state, by providing explicit extension points
+for common plugin requirements.
+
+Capable Plugins classes must implement the [`Composer\Plugin\Capable`][8] interface
+and declare their capabilities in the `getCapabilities()` method.
+This method must return an array, with the _key_ as a Composer Capability class name,
+and the _value_ as the Plugin's own implementation class name of said Capability:
+
+```php
+<?php
+
+namespace My\Composer;
+
+use Composer\Composer;
+use Composer\IO\IOInterface;
+use Composer\Plugin\PluginInterface;
+use Composer\Plugin\Capable;
+
+class Plugin implements PluginInterface, Capable
+{
+    public function activate(Composer $composer, IOInterface $io)
+    {
+    }
+
+    public function getCapabilities()
+    {
+        return array(
+            'Composer\Plugin\Capability\CommandProvider' => 'My\Composer\CommandProvider',
+        );
+    }
+}
+```
+
+### Command provider
+
+The [`Composer\Plugin\Capability\CommandProvider`][9] capability allows to register
+additional commands for Composer :
+
+```php
+<?php
+
+namespace My\Composer;
+
+use Composer\Plugin\Capability\CommandProvider as CommandProviderCapability;
+use Symfony\Component\Console\Input\InputInterface;
+use Symfony\Component\Console\Output\OutputInterface;
+use Composer\Command\BaseCommand;
+
+class CommandProvider implements CommandProviderCapability
+{
+    public function getCommands()
+    {
+        return array(new Command);
+    }
+}
+
+class Command extends BaseCommand
+{
+    protected function configure()
+    {
+        $this->setName('custom-plugin-command');
+    }
+
+    protected function execute(InputInterface $input, OutputInterface $output)
+    {
+        $output->writeln('Executing');
+    }
+}
+```
+
+Now the `custom-plugin-command` is available alongside Composer commands.
+
+> _Composer commands are based on the [Symfony Console Component][10]._
+
+## Using Plugins
+
+Plugin packages are automatically loaded as soon as they are installed and will
+be loaded when composer starts up if they are found in the current project's
+list of installed packages. Additionally all plugin packages installed in the
+`COMPOSER_HOME` directory using the composer global command are loaded before
+local project plugins are loaded.
+
+> You may pass the `--no-plugins` option to composer commands to disable all
+> installed plugins. This may be particularly helpful if any of the plugins
+> causes errors and you wish to update or uninstall it.
+
+[1]: ../04-schema.md#type
+[2]: ../04-schema.md#extra
+[3]: https://github.com/composer/composer/blob/master/src/Composer/Plugin/PluginInterface.php
+[4]: https://github.com/composer/composer/blob/master/src/Composer/Composer.php
+[5]: https://github.com/composer/composer/blob/master/src/Composer/IO/IOInterface.php
+[6]: https://github.com/composer/composer/blob/master/src/Composer/EventDispatcher/EventSubscriberInterface.php
+[7]: ../01-basic-usage.md#package-versions
+[8]: https://github.com/composer/composer/blob/master/src/Composer/Plugin/Capable.php
+[9]: https://github.com/composer/composer/blob/master/src/Composer/Plugin/Capability/CommandProvider.php
+[10]: https://symfony.com/doc/current/components/console.html

data/helpers/vendor/composer/composer/doc/articles/scripts.md

@@ -0,0 +1,304 @@
+<!--
+    tagline: Script are callbacks that are called before/after installing packages
+-->
+
+# Scripts
+
+## What is a script?
+
+A script, in Composer's terms, can either be a PHP callback (defined as a
+static method) or any command-line executable command. Scripts are useful
+for executing a package's custom code or package-specific commands during
+the Composer execution process.
+
+> **Note:** Only scripts defined in the root package's `composer.json` are
+> executed. If a dependency of the root package specifies its own scripts,
+> Composer does not execute those additional scripts.
+
+## Event names
+
+Composer fires the following named events during its execution process:
+
+### Command Events
+
+- **pre-install-cmd**: occurs before the `install` command is executed with a
+  lock file present.
+- **post-install-cmd**: occurs after the `install` command has been executed
+  with a lock file present.
+- **pre-update-cmd**: occurs before the `update` command is executed, or before
+  the `install` command is executed without a lock file present.
+- **post-update-cmd**: occurs after the `update` command has been executed, or
+  after the `install` command has been executed without a lock file present.
+- **post-status-cmd**: occurs after the `status` command has been executed.
+- **pre-archive-cmd**: occurs before the `archive` command is executed.
+- **post-archive-cmd**: occurs after the `archive` command has been executed.
+- **pre-autoload-dump**: occurs before the autoloader is dumped, either during
+  `install`/`update`, or via the `dump-autoload` command.
+- **post-autoload-dump**: occurs after the autoloader has been dumped, either
+  during `install`/`update`, or via the `dump-autoload` command.
+- **post-root-package-install**: occurs after the root package has been
+  installed, during the `create-project` command.
+- **post-create-project-cmd**: occurs after the `create-project` command has
+  been executed.
+
+### Installer Events
+
+- **pre-dependencies-solving**: occurs before the dependencies are resolved.
+- **post-dependencies-solving**: occurs after the dependencies have been resolved.
+
+### Package Events
+
+- **pre-package-install**: occurs before a package is installed.
+- **post-package-install**: occurs after a package has been installed.
+- **pre-package-update**: occurs before a package is updated.
+- **post-package-update**: occurs after a package has been updated.
+- **pre-package-uninstall**: occurs before a package is uninstalled.
+- **post-package-uninstall**: occurs after a package has been uninstalled.
+
+### Plugin Events
+
+- **init**: occurs after a Composer instance is done being initialized.
+- **command**: occurs before any Composer Command is executed on the CLI. It
+  provides you with access to the input and output objects of the program.
+- **pre-file-download**: occurs before files are downloaded and allows
+  you to manipulate the `RemoteFilesystem` object prior to downloading files
+  based on the URL to be downloaded.
+- **pre-command-run**: occurs before a command is executed and allows you to
+  manipulate the `InputInterface` object's options and arguments to tweak
+  a command's behavior.
+
+> **Note:** Composer makes no assumptions about the state of your dependencies
+> prior to `install` or `update`. Therefore, you should not specify scripts
+> that require Composer-managed dependencies in the `pre-update-cmd` or
+> `pre-install-cmd` event hooks. If you need to execute scripts prior to
+> `install` or `update` please make sure they are self-contained within your
+> root package.
+
+## Defining scripts
+
+The root JSON object in `composer.json` should have a property called
+`"scripts"`, which contains pairs of named events and each event's
+corresponding scripts. An event's scripts can be defined as either a string
+(only for a single script) or an array (for single or multiple scripts.)
+
+For any given event:
+
+- Scripts execute in the order defined when their corresponding event is fired.
+- An array of scripts wired to a single event can contain both PHP callbacks
+and command-line executable commands.
+- PHP classes containing defined callbacks must be autoloadable via Composer's
+autoload functionality.
+- Callbacks can only autoload classes from psr-0, psr-4 and classmap
+definitions. If a defined callback relies on functions defined outside of a
+class, the callback itself is responsible for loading the file containing these
+functions.
+
+Script definition example:
+
+```json
+{
+    "scripts": {
+        "post-update-cmd": "MyVendor\\MyClass::postUpdate",
+        "post-package-install": [
+            "MyVendor\\MyClass::postPackageInstall"
+        ],
+        "post-install-cmd": [
+            "MyVendor\\MyClass::warmCache",
+            "phpunit -c app/"
+        ],
+        "post-autoload-dump": [
+            "MyVendor\\MyClass::postAutoloadDump"
+        ],
+        "post-create-project-cmd": [
+            "php -r \"copy('config/local-example.php', 'config/local.php');\""
+        ]
+    }
+}
+```
+
+Using the previous definition example, here's the class `MyVendor\MyClass`
+that might be used to execute the PHP callbacks:
+
+```php
+<?php
+
+namespace MyVendor;
+
+use Composer\Script\Event;
+use Composer\Installer\PackageEvent;
+
+class MyClass
+{
+    public static function postUpdate(Event $event)
+    {
+        $composer = $event->getComposer();
+        // do stuff
+    }
+
+    public static function postAutoloadDump(Event $event)
+    {
+        $vendorDir = $event->getComposer()->getConfig()->get('vendor-dir');
+        require $vendorDir . '/autoload.php';
+
+        some_function_from_an_autoloaded_file();
+    }
+
+    public static function postPackageInstall(PackageEvent $event)
+    {
+        $installedPackage = $event->getOperation()->getPackage();
+        // do stuff
+    }
+
+    public static function warmCache(Event $event)
+    {
+        // make cache toasty
+    }
+}
+```
+
+**Note:** During a composer install or update process, a variable named
+`COMPOSER_DEV_MODE` will be added to the environment. If the command was run
+with the `--no-dev` flag, this variable will be set to 0, otherwise it will be
+set to 1.
+
+## Event classes
+
+When an event is fired, your PHP callback receives as first argument a
+`Composer\EventDispatcher\Event` object. This object has a `getName()` method
+that lets you retrieve the event name.
+
+Depending on the [script types](#event-names) you will get various event
+subclasses containing various getters with relevant data and associated
+objects:
+
+- Base class: [`Composer\EventDispatcher\Event`](https://getcomposer.org/apidoc/master/Composer/EventDispatcher/Event.html)
+- Command Events: [`Composer\Script\Event`](https://getcomposer.org/apidoc/master/Composer/Script/Event.html)
+- Installer Events: [`Composer\Installer\InstallerEvent`](https://getcomposer.org/apidoc/master/Composer/Installer/InstallerEvent.html)
+- Package Events: [`Composer\Installer\PackageEvent`](https://getcomposer.org/apidoc/master/Composer/Installer/PackageEvent.html)
+- Plugin Events:
+  - init: [`Composer\EventDispatcher\Event`](https://getcomposer.org/apidoc/master/Composer/EventDispatcher/Event.html)
+  - command: [`Composer\Plugin\CommandEvent`](https://getcomposer.org/apidoc/master/Composer/Plugin/CommandEvent.html)
+  - pre-file-download: [`Composer\Plugin\PreFileDownloadEvent`](https://getcomposer.org/apidoc/master/Composer/Plugin/PreFileDownloadEvent.html)
+
+## Running scripts manually
+
+If you would like to run the scripts for an event manually, the syntax is:
+
+```sh
+composer run-script [--dev] [--no-dev] script
+```
+
+For example `composer run-script post-install-cmd` will run any
+**post-install-cmd** scripts that have been defined.
+
+You can also give additional arguments to the script handler by appending `--`
+followed by the handler arguments. e.g.
+`composer run-script post-install-cmd -- --check` will pass`--check` along to
+the script handler. Those arguments are received as CLI arg by CLI handlers,
+and can be retrieved as an array via `$event->getArguments()` by PHP handlers.
+
+## Writing custom commands
+
+If you add custom scripts that do not fit one of the predefined event name
+above, you can either run them with run-script or also run them as native
+Composer commands. For example the handler defined below is executable by
+simply running `composer test`:
+
+```json
+{
+    "scripts": {
+        "test": "phpunit"
+    }
+}
+```
+
+Similar to the `run-script` command you can give additional arguments to scripts,
+e.g. `composer test -- --filter <pattern>` will pass `--filter <pattern>` along
+to the `phpunit` script.
+
+> **Note:** Before executing scripts, Composer's bin-dir is temporarily pushed
+> on top of the PATH environment variable so that binaries of dependencies
+> are easily accessible. In this example no matter if the `phpunit` binary is
+> actually in `vendor/bin/phpunit` or `bin/phpunit` it will be found and executed.
+
+## Referencing scripts
+
+To enable script re-use and avoid duplicates, you can call a script from another
+one by prefixing the command name with `@`:
+
+```json
+{
+    "scripts": {
+        "test": [
+            "@clearCache",
+            "phpunit"
+        ],
+        "clearCache": "rm -rf cache/*"
+    }
+}
+```
+
+You can also refer a script and pass it new arguments:
+
+```json
+{
+  "scripts": {
+    "tests": "phpunit",
+    "testsVerbose": "@tests -vvv"
+  }
+}
+```
+
+## Calling Composer commands
+
+To call Composer commands, you can use `@composer` which will automatically
+resolve to whatever composer.phar is currently being used:
+
+```json
+{
+    "scripts": {
+        "test": [
+            "@composer install",
+            "phpunit"
+        ]
+    }
+}
+```
+
+One limitation of this is that you can not call multiple composer commands in
+a row like `@composer install && @composer foo`. You must split them up in a
+JSON array of commands.
+
+## Executing PHP scripts
+
+To execute PHP scripts, you can use `@php` which will automatically
+resolve to whatever php process is currently being used:
+
+```json
+{
+    "scripts": {
+        "test": [
+            "@php script.php",
+            "phpunit"
+        ]
+    }
+}
+```
+
+One limitation of this is that you can not call multiple commands in
+a row like `@php install && @php foo`. You must split them up in a
+JSON array of commands.
+
+## Custom descriptions.
+
+You can set custom script descriptions with the following in your `composer.json`:
+
+```json
+{
+    "scripts-descriptions": {
+        "test": "Run all tests!"
+    }
+}
+```
+
+> **Note:** You can only set custom descriptions of custom commands.