dependabot-composer 0.106.4 → 0.106.5

data/helpers/vendor/composer/composer/doc/00-intro.md

@@ -0,0 +1,156 @@
+# Introduction
+
+Composer is a tool for dependency management in PHP. It allows you to declare
+the libraries your project depends on and it will manage (install/update) them
+for you.
+
+## Dependency management
+
+Composer is **not** a package manager in the same sense as Yum or Apt are. Yes,
+it deals with "packages" or libraries, but it manages them on a per-project
+basis, installing them in a directory (e.g. `vendor`) inside your project. By
+default it does not install anything globally. Thus, it is a dependency
+manager. It does however support a "global" project for convenience via the
+[global](03-cli.md#global) command.
+
+This idea is not new and Composer is strongly inspired by node's
+[npm](https://www.npmjs.com/) and ruby's [bundler](https://bundler.io/).
+
+Suppose:
+
+1. You have a project that depends on a number of libraries.
+1. Some of those libraries depend on other libraries.
+
+Composer:
+
+1. Enables you to declare the libraries you depend on.
+1. Finds out which versions of which packages can and need to be installed, and
+   installs them (meaning it downloads them into your project).
+
+See the [Basic usage](01-basic-usage.md) chapter for more details on declaring
+dependencies.
+
+## System Requirements
+
+Composer requires PHP 5.3.2+ to run. A few sensitive php settings and compile
+flags are also required, but when using the installer you will be warned about
+any incompatibilities.
+
+To install packages from sources instead of simple zip archives, you will need
+git, svn, fossil or hg depending on how the package is version-controlled.
+
+Composer is multi-platform and we strive to make it run equally well on Windows,
+Linux and macOS.
+
+## Installation - Linux / Unix / macOS
+
+### Downloading the Composer Executable
+
+Composer offers a convenient installer that you can execute directly from the
+commandline. Feel free to [download this file](https://getcomposer.org/installer)
+or review it on [GitHub](https://github.com/composer/getcomposer.org/blob/master/web/installer)
+if you wish to know more about the inner workings of the installer. The source
+is plain PHP.
+
+There are in short, two ways to install Composer. Locally as part of your
+project, or globally as a system wide executable.
+
+#### Locally
+
+To install Composer locally, run the installer in your project directory. See 
+[the Download page](https://getcomposer.org/download/) for instructions.
+
+The installer will check a few PHP settings and then download `composer.phar`
+to your working directory. This file is the Composer binary. It is a PHAR
+(PHP archive), which is an archive format for PHP which can be run on
+the command line, amongst other things.
+
+Now run `php composer.phar` in order to run Composer.
+
+You can install Composer to a specific directory by using the `--install-dir`
+option and additionally (re)name it as well using the `--filename` option. When
+running the installer when following
+[the Download page instructions](https://getcomposer.org/download/) add the
+following parameters:
+
+```sh
+php composer-setup.php --install-dir=bin --filename=composer
+```
+
+Now run `php bin/composer` in order to run Composer.
+
+#### Globally
+
+You can place the Composer PHAR anywhere you wish. If you put it in a directory
+that is part of your `PATH`, you can access it globally. On unixy systems you
+can even make it executable and invoke it without directly using the `php`
+interpreter.
+
+After running the installer following [the Download page instructions](https://getcomposer.org/download/)
+you can run this to move composer.phar to a directory that is in your path:
+
+```sh
+mv composer.phar /usr/local/bin/composer
+```
+
+If you like to install it only for your user and avoid requiring root permissions,
+you can use `~/.local/bin` instead which is available by default on some
+Linux distributions.
+
+> **Note:** If the above fails due to permissions, you may need to run it again
+> with sudo.
+
+> **Note:** On some versions of macOS the `/usr` directory does not exist by
+> default. If you receive the error "/usr/local/bin/composer: No such file or
+> directory" then you must create the directory manually before proceeding:
+> `mkdir -p /usr/local/bin`.
+
+> **Note:** For information on changing your PATH, please read the
+> [Wikipedia article](https://en.wikipedia.org/wiki/PATH_(variable)) and/or use Google.
+
+Now run `composer` in order to run Composer instead of `php composer.phar`.
+
+## Installation - Windows
+
+### Using the Installer
+
+This is the easiest way to get Composer set up on your machine.
+
+Download and run
+[Composer-Setup.exe](https://getcomposer.org/Composer-Setup.exe). It will
+install the latest Composer version and set up your PATH so that you can
+call `composer` from any directory in your command line.
+
+> **Note:** Close your current terminal. Test usage with a new terminal: This is
+> important since the PATH only gets loaded when the terminal starts.
+
+### Manual Installation
+
+Change to a directory on your `PATH` and run the installer following
+[the Download page instructions](https://getcomposer.org/download/)
+to download `composer.phar`.
+
+Create a new `composer.bat` file alongside `composer.phar`:
+
+```sh
+C:\bin>echo @php "%~dp0composer.phar" %*>composer.bat
+```
+
+Add the directory to your PATH environment variable if it isn't already.
+For information on changing your PATH variable, please see
+[this article](https://www.computerhope.com/issues/ch000549.htm) and/or
+use Google.
+
+Close your current terminal. Test usage with a new terminal:
+
+```sh
+C:\Users\username>composer -V
+Composer version 1.0.0 2016-01-10 20:34:53
+```
+
+## Using Composer
+
+Now that you've installed Composer, you are ready to use it! Head on over to the
+next chapter for a short and simple demonstration.
+
+[Basic usage](01-basic-usage.md) →

data/helpers/vendor/composer/composer/doc/01-basic-usage.md

@@ -0,0 +1,266 @@
+# Basic usage
+
+## Introduction
+
+For our basic usage introduction, we will be installing `monolog/monolog`,
+a logging library. If you have not yet installed Composer, refer to the
+[Intro](00-intro.md) chapter.
+
+> **Note:** for the sake of simplicity, this introduction will assume you
+> have performed a [local](00-intro.md#locally) install of Composer.
+
+## `composer.json`: Project Setup
+
+To start using Composer in your project, all you need is a `composer.json`
+file. This file describes the dependencies of your project and may contain
+other metadata as well.
+
+### The `require` Key
+
+The first (and often only) thing you specify in `composer.json` is the
+[`require`](04-schema.md#require) key. You are simply telling Composer which
+packages your project depends on.
+
+```json
+{
+    "require": {
+        "monolog/monolog": "1.0.*"
+    }
+}
+```
+
+As you can see, [`require`](04-schema.md#require) takes an object that maps
+**package names** (e.g. `monolog/monolog`) to **version constraints** (e.g.
+`1.0.*`).
+
+Composer uses this information to search for the right set of files in package
+"repositories" that you register using the [`repositories`](04-schema.md#repositories)
+key, or in Packagist, the default package repository. In the above example,
+since no other repository has been registered in the `composer.json` file, it is
+assumed that the `monolog/monolog` package is registered on Packagist. (See more
+about Packagist [below](#packagist), or read more about repositories
+[here](05-repositories.md)).
+
+### Package Names
+
+The package name consists of a vendor name and the project's name. Often these
+will be identical - the vendor name only exists to prevent naming clashes. For
+example, it would allow two different people to create a library named `json`.
+One might be named `igorw/json` while the other might be `seldaek/json`.
+
+Read more about publishing packages and package naming [here](02-libraries.md).
+(Note that you can also specify "platform packages" as dependencies, allowing
+you to require certain versions of server software. See
+[platform packages](#platform-packages) below.)
+
+### Package Version Constraints
+
+In our example, we are requesting the Monolog package with the version constraint
+[`1.0.*`](https://semver.mwl.be/#?package=monolog%2Fmonolog&version=1.0.*).
+This means any version in the `1.0` development branch, or any version that is
+greater than or equal to 1.0 and less than 1.1 (`>=1.0 <1.1`).
+
+Please read [versions](articles/versions.md) for more in-depth information on
+versions, how versions relate to each other, and on version constraints.
+
+> **How does Composer download the right files?** When you specify a dependency in
+> `composer.json`, Composer first takes the name of the package that you have requested
+> and searches for it in any repositories that you have registered using the
+> [`repositories`](04-schema.md#repositories) key. If you have not registered
+> any extra repositories, or it does not find a package with that name in the
+> repositories you have specified, it falls back to Packagist (more [below](#packagist)).
+>
+> When Composer finds the right package, either in Packagist or in a repo you have specified,
+> it then uses the versioning features of the package's VCS (i.e., branches and tags)
+> to attempt to find the best match for the version constraint you have specified. Be sure to read
+> about versions and package resolution in the [versions article](articles/versions.md).
+
+> **Note:** If you are trying to require a package but Composer throws an error
+> regarding package stability, the version you have specified may not meet your
+> default minimum stability requirements. By default only stable releases are taken
+> into consideration when searching for valid package versions in your VCS.
+>
+> You might run into this if you are trying to require dev, alpha, beta, or RC
+> versions of a package. Read more about stability flags and the `minimum-stability`
+> key on the [schema page](04-schema.md).
+
+## Installing Dependencies
+
+To install the defined dependencies for your project, run the
+[`install`](03-cli.md#install) command.
+
+```sh
+php composer.phar install
+```
+
+When you run this command, one of two things may happen:
+
+### Installing Without `composer.lock`
+
+If you have never run the command before and there is also no `composer.lock` file present,
+Composer simply resolves all dependencies listed in your `composer.json` file and downloads
+the latest version of their files into the `vendor` directory in your project. (The `vendor`
+directory is the conventional location for all third-party code in a project). In our
+example from above, you would end up with the Monolog source files in
+`vendor/monolog/monolog/`. If Monolog listed any dependencies, those would also be in
+folders under `vendor/`.
+
+> **Tip:** If you are using git for your project, you probably want to add
+> `vendor` in your `.gitignore`. You really don't want to add all of that
+> third-party code to your versioned repository.
+
+When Composer has finished installing, it writes all of the packages and the exact versions
+of them that it downloaded to the `composer.lock` file, locking the project to those specific
+versions. You should commit the `composer.lock` file to your project repo so that all people
+working on the project are locked to the same versions of dependencies (more below).
+
+### Installing With `composer.lock`
+
+This brings us to the second scenario. If there is already a `composer.lock` file as well as a
+`composer.json` file when you run `composer install`, it means either you ran the
+`install` command before, or someone else on the project ran the `install` command and
+committed the `composer.lock` file to the project (which is good).
+
+Either way, running `install` when a `composer.lock` file is present resolves and installs
+all dependencies that you listed in `composer.json`, but Composer uses the exact versions listed
+in `composer.lock` to ensure that the package versions are consistent for everyone
+working on your project. As a result you will have all dependencies requested by your
+`composer.json` file, but they may not all be at the very latest available versions
+(some of the dependencies listed in the `composer.lock` file may have released newer versions since
+the file was created). This is by design, it ensures that your project does not break because of
+unexpected changes in dependencies.
+
+### Commit Your `composer.lock` File to Version Control
+
+Committing this file to VC is important because it will cause anyone who sets
+up the project to use the exact same
+versions of the dependencies that you are using. Your CI server, production
+machines, other developers in your team, everything and everyone runs on the
+same dependencies, which mitigates the potential for bugs affecting only some
+parts of the deployments. Even if you develop alone, in six months when
+reinstalling the project you can feel confident the dependencies installed are
+still working even if your dependencies released many new versions since then.
+(See note below about using the `update` command.)
+
+## Updating Dependencies to their Latest Versions
+
+As mentioned above, the `composer.lock` file prevents you from automatically getting
+the latest versions of your dependencies. To update to the latest versions, use the
+[`update`](03-cli.md#update) command. This will fetch the latest matching
+versions (according to your `composer.json` file) and update the lock file
+with the new versions. (This is equivalent to deleting the `composer.lock` file
+and running `install` again.)
+
+```sh
+php composer.phar update
+```
+
+> **Note:** Composer will display a Warning when executing an `install` command
+> if the `composer.lock` has not been updated since changes were made to the
+> `composer.json` that might affect dependency resolution.
+
+If you only want to install or update one dependency, you can whitelist them:
+
+```sh
+php composer.phar update monolog/monolog [...]
+```
+
+> **Note:** For libraries it is not necessary to commit the lock
+> file, see also: [Libraries - Lock file](02-libraries.md#lock-file).
+
+## Packagist
+
+[Packagist](https://packagist.org/) is the main Composer repository. A Composer
+repository is basically a package source: a place where you can get packages
+from. Packagist aims to be the central repository that everybody uses. This
+means that you can automatically `require` any package that is available there,
+without further specifying where Composer should look for the package.
+
+If you go to the [Packagist website](https://packagist.org/) (packagist.org),
+you can browse and search for packages.
+
+Any open source project using Composer is recommended to publish their packages
+on Packagist. A library does not need to be on Packagist to be used by Composer,
+but it enables discovery and adoption by other developers more quickly.
+
+## Platform packages
+
+Composer has platform packages, which are virtual packages for things that are
+installed on the system but are not actually installable by Composer. This
+includes PHP itself, PHP extensions and some system libraries.
+
+* `php` represents the PHP version of the user, allowing you to apply
+  constraints, e.g. `^7.1`. To require a 64bit version of php, you can
+  require the `php-64bit` package.
+
+* `hhvm` represents the version of the HHVM runtime and allows you to apply
+  a constraint, e.g., `^2.3`.
+
+* `ext-<name>` allows you to require PHP extensions (includes core
+  extensions). Versioning can be quite inconsistent here, so it's often
+  a good idea to set the constraint to `*`.  An example of an extension
+  package name is `ext-gd`.
+
+* `lib-<name>` allows constraints to be made on versions of libraries used by
+  PHP. The following are available: `curl`, `iconv`, `icu`, `libxml`,
+  `openssl`, `pcre`, `uuid`, `xsl`.
+
+You can use [`show --platform`](03-cli.md#show) to get a list of your locally
+available platform packages.
+
+## Autoloading
+
+For libraries that specify autoload information, Composer generates a
+`vendor/autoload.php` file. You can simply include this file and start
+using the classes that those libraries provide without any extra work:
+
+```php
+require __DIR__ . '/vendor/autoload.php';
+
+$log = new Monolog\Logger('name');
+$log->pushHandler(new Monolog\Handler\StreamHandler('app.log', Monolog\Logger::WARNING));
+$log->addWarning('Foo');
+```
+
+You can even add your own code to the autoloader by adding an
+[`autoload`](04-schema.md#autoload) field to `composer.json`.
+
+```json
+{
+    "autoload": {
+        "psr-4": {"Acme\\": "src/"}
+    }
+}
+```
+
+Composer will register a [PSR-4](http://www.php-fig.org/psr/psr-4/) autoloader
+for the `Acme` namespace.
+
+You define a mapping from namespaces to directories. The `src` directory would
+be in your project root, on the same level as `vendor` directory is. An example
+filename would be `src/Foo.php` containing an `Acme\Foo` class.
+
+After adding the [`autoload`](04-schema.md#autoload) field, you have to re-run
+[`dump-autoload`](03-cli.md#dump-autoload) to re-generate the
+`vendor/autoload.php` file.
+
+Including that file will also return the autoloader instance, so you can store
+the return value of the include call in a variable and add more namespaces.
+This can be useful for autoloading classes in a test suite, for example.
+
+```php
+$loader = require __DIR__ . '/vendor/autoload.php';
+$loader->addPsr4('Acme\\Test\\', __DIR__);
+```
+
+In addition to PSR-4 autoloading, Composer also supports PSR-0, classmap and
+files autoloading. See the [`autoload`](04-schema.md#autoload) reference for
+more information.
+
+See also the docs on [optimizing the autoloader](articles/autoloader-optimization.md).
+
+> **Note:** Composer provides its own autoloader. If you don't want to use that
+> one, you can include `vendor/composer/autoload_*.php` files, which return
+> associative arrays allowing you to configure your own autoloader.
+
+&larr; [Intro](00-intro.md)  |  [Libraries](02-libraries.md) &rarr;

data/helpers/vendor/composer/composer/doc/02-libraries.md

@@ -0,0 +1,153 @@
+# Libraries
+
+This chapter will tell you how to make your library installable through
+Composer.
+
+## Every project is a package
+
+As soon as you have a `composer.json` in a directory, that directory is a
+package. When you add a [`require`](04-schema.md#require) to a project, you are
+making a package that depends on other packages. The only difference between
+your project and a library is that your project is a package without a name.
+
+In order to make that package installable you need to give it a name. You do
+this by adding the [`name`](04-schema.md#name) property in `composer.json`:
+
+```json
+{
+    "name": "acme/hello-world",
+    "require": {
+        "monolog/monolog": "1.0.*"
+    }
+}
+```
+
+In this case the project name is `acme/hello-world`, where `acme` is the vendor
+name. Supplying a vendor name is mandatory.
+
+> **Note:** If you don't know what to use as a vendor name, your GitHub
+> username is usually a good bet. While package names are case insensitive, the
+> convention is all lowercase and dashes for word separation.
+
+## Library Versioning
+
+In the vast majority of cases, you will be maintaining your library using some
+sort of version control system like git, svn, hg or fossil. In these cases,
+Composer infers versions from your VCS and you **should not** specify a version
+in your `composer.json` file. (See the [Versions article](articles/versions.md)
+to learn about how Composer uses VCS branches and tags to resolve version
+constraints.)
+
+If you are maintaining packages by hand (i.e., without a VCS), you'll need to
+specify the version explicitly by adding a `version` value in your `composer.json`
+file:
+
+```json
+{
+    "version": "1.0.0"
+}
+```
+
+> **Note:** When you add a hardcoded version to a VCS, the version will conflict
+> with tag names. Composer will not be able to determine the version number.
+
+### VCS Versioning
+
+Composer uses your VCS's branch and tag features to resolve the version
+constraints you specify in your `require` field to specific sets of files.
+When determining valid available versions, Composer looks at all of your tags
+and branches and translates their names into an internal list of options that
+it then matches against the version constraint you provided.
+
+For more on how Composer treats tags and branches and how it resolves package
+version constraints, read the [versions](articles/versions.md) article.
+
+## Lock file
+
+For your library you may commit the `composer.lock` file if you want to. This
+can help your team to always test against the same dependency versions.
+However, this lock file will not have any effect on other projects that depend
+on it. It only has an effect on the main project.
+
+If you do not want to commit the lock file and you are using git, add it to
+the `.gitignore`.
+
+## Publishing to a VCS
+
+Once you have a VCS repository (version control system, e.g. git) containing a
+`composer.json` file, your library is already composer-installable. In this
+example we will publish the `acme/hello-world` library on GitHub under
+`github.com/username/hello-world`.
+
+Now, to test installing the `acme/hello-world` package, we create a new
+project locally. We will call it `acme/blog`. This blog will depend on
+`acme/hello-world`, which in turn depends on `monolog/monolog`. We can
+accomplish this by creating a new `blog` directory somewhere, containing a
+`composer.json`:
+
+```json
+{
+    "name": "acme/blog",
+    "require": {
+        "acme/hello-world": "dev-master"
+    }
+}
+```
+
+The name is not needed in this case, since we don't want to publish the blog
+as a library. It is added here to clarify which `composer.json` is being
+described.
+
+Now we need to tell the blog app where to find the `hello-world` dependency.
+We do this by adding a package repository specification to the blog's
+`composer.json`:
+
+```json
+{
+    "name": "acme/blog",
+    "repositories": [
+        {
+            "type": "vcs",
+            "url": "https://github.com/username/hello-world"
+        }
+    ],
+    "require": {
+        "acme/hello-world": "dev-master"
+    }
+}
+```
+
+For more details on how package repositories work and what other types are
+available, see [Repositories](05-repositories.md).
+
+That's all. You can now install the dependencies by running Composer's
+[`install`](03-cli.md#install) command!
+
+**Recap:** Any git/svn/hg/fossil repository containing a `composer.json` can be
+added to your project by specifying the package repository and declaring the
+dependency in the [`require`](04-schema.md#require) field.
+
+## Publishing to packagist
+
+Alright, so now you can publish packages. But specifying the VCS repository
+every time is cumbersome. You don't want to force all your users to do that.
+
+The other thing that you may have noticed is that we did not specify a package
+repository for `monolog/monolog`. How did that work? The answer is Packagist.
+
+[Packagist](https://packagist.org/) is the main package repository for
+Composer, and it is enabled by default. Anything that is published on
+Packagist is available automatically through Composer. Since
+[Monolog is on Packagist](https://packagist.org/packages/monolog/monolog), we
+can depend on it without having to specify any additional repositories.
+
+If we wanted to share `hello-world` with the world, we would publish it on
+Packagist as well. Doing so is really easy.
+
+You simply visit [Packagist](https://packagist.org) and hit the "Submit"
+button. This will prompt you to sign up if you haven't already, and then
+allows you to submit the URL to your VCS repository, at which point Packagist
+will start crawling it. Once it is done, your package will be available to
+anyone!
+
+← [Basic usage](01-basic-usage.md) |  [Command-line interface](03-cli.md) →