dependabot-composer 0.95.42 → 0.95.43

data/helpers/vendor/composer/composer/doc/articles/custom-installers.md

@@ -1,204 +0,0 @@
-<!--
-    tagline: Modify the way certain types of packages are installed
--->
-
-# Setting up and using custom installers
-
-## Synopsis
-
-At times it may be necessary for a package to require additional actions during
-installation, such as installing packages outside of the default `vendor`
-library.
-
-In these cases you could consider creating a Custom Installer to handle your
-specific logic.
-
-## Calling a Custom Installer
-
-Suppose that your project already has a Custom Installer for specific modules
-then invoking that installer is a matter of defining the correct [type][1] in
-your package file.
-
-> _See the next chapter for an instruction how to create Custom Installers._
-
-Every Custom Installer defines which [type][1] string it will recognize. Once
-recognized it will completely override the default installer and only apply its
-own logic.
-
-An example use-case would be:
-
-> phpDocumentor features Templates that need to be installed outside of the
-> default /vendor folder structure. As such they have chosen to adopt the
-> `phpdocumentor-template` [type][1] and create a plugin providing the Custom
-> Installer to send these templates to the correct folder.
-
-An example composer.json of such a template package would be:
-
-```json
-{
-    "name": "phpdocumentor/template-responsive",
-    "type": "phpdocumentor-template",
-    "require": {
-        "phpdocumentor/template-installer-plugin": "*"
-    }
-}
-```
-
-> **IMPORTANT**: to make sure that the template installer is present at the
-> time the template package is installed, template packages should require
-> the plugin package.
-
-## Creating an Installer
-
-A Custom Installer is defined as a class that implements the
-[`Composer\Installer\InstallerInterface`][4] and is usually distributed in a
-Composer Plugin.
-
-A basic Installer Plugin would thus compose of three files:
-
-1. the package file: composer.json
-2. The Plugin class, e.g.: `My\Project\Composer\Plugin.php`, containing a class that implements `Composer\Plugin\PluginInterface`.
-3. The Installer class, e.g.: `My\Project\Composer\Installer.php`, containing a class that implements `Composer\Installer\InstallerInterface`.
-
-### composer.json
-
-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.
-
-Example:
-
-```json
-{
-    "name": "phpdocumentor/template-installer-plugin",
-    "type": "composer-plugin",
-    "license": "MIT",
-    "autoload": {
-        "psr-0": {"phpDocumentor\\Composer": "src/"}
-    },
-    "extra": {
-        "class": "phpDocumentor\\Composer\\TemplateInstallerPlugin"
-    },
-    "require": {
-        "composer-plugin-api": "^1.0"
-    },
-    "require-dev": {
-        "composer/composer": "^1.3"
-    }
-}
-```
-
-The example above has Composer itself in its require-dev, which allows you to use
-the Composer classes in your test suite for example.
-
-### The Plugin class
-
-The class defining the Composer plugin must implement the
-[`Composer\Plugin\PluginInterface`][3]. It can then register the Custom
-Installer in its `activate()` method.
-
-The class may be placed in any location and have any name, as long as it is
-autoloadable and matches the `extra.class` element in the package definition.
-
-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);
-    }
-}
-```
-
-### The Custom Installer class
-
-The class that executes the custom installation should implement the
-[`Composer\Installer\InstallerInterface`][4] (or extend another installer that
-implements that interface). It defines the [type][1] string as it will be
-recognized by packages that will use this installer in the `supports()` method.
-
-> **NOTE**: _choose your [type][1] name carefully, it is recommended to follow
-> the format: `vendor-type`_. For example: `phpdocumentor-template`.
-
-The InstallerInterface class defines the following methods (please see the
-source for the exact signature):
-
-* **supports()**, here you test whether the passed [type][1] matches the name
-  that you declared for this installer (see the example).
-* **isInstalled()**, determines whether a supported package is installed or not.
-* **install()**, here you can determine the actions that need to be executed
-  upon installation.
-* **update()**, here you define the behavior that is required when Composer is
-  invoked with the update argument.
-* **uninstall()**, here you can determine the actions that need to be executed
-  when the package needs to be removed.
-* **getInstallPath()**, this method should return the location where the
-  package is to be installed, _relative from the location of composer.json._
-
-Example:
-
-```php
-<?php
-
-namespace phpDocumentor\Composer;
-
-use Composer\Package\PackageInterface;
-use Composer\Installer\LibraryInstaller;
-
-class TemplateInstaller extends LibraryInstaller
-{
-    /**
-     * {@inheritDoc}
-     */
-    public function getInstallPath(PackageInterface $package)
-    {
-        $prefix = substr($package->getPrettyName(), 0, 23);
-        if ('phpdocumentor/template-' !== $prefix) {
-            throw new \InvalidArgumentException(
-                'Unable to install template, phpdocumentor templates '
-                .'should always start their package name with '
-                .'"phpdocumentor/template-"'
-            );
-        }
-
-        return 'data/templates/'.substr($package->getPrettyName(), 23);
-    }
-
-    /**
-     * {@inheritDoc}
-     */
-    public function supports($packageType)
-    {
-        return 'phpdocumentor-template' === $packageType;
-    }
-}
-```
-
-The example demonstrates that it is quite simple to extend the
-[`Composer\Installer\LibraryInstaller`][5] class to strip a prefix
-(`phpdocumentor/template-`) and use the remaining part to assemble a completely
-different installation path.
-
-> _Instead of being installed in `/vendor` any package installed using this
-> Installer will be put in the `/data/templates/<stripped name>` folder._
-
-[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/Installer/InstallerInterface.php
-[5]: https://github.com/composer/composer/blob/master/src/Composer/Installer/LibraryInstaller.php

data/helpers/vendor/composer/composer/doc/articles/handling-private-packages-with-satis.md

@@ -1,343 +0,0 @@
-<!--
-    tagline: Hosting and installing private Composer packages
--->
-
-# Handling private packages
-
-# Private Packagist
-
-[Private Packagist](https://packagist.com) is a commercial package hosting product
-offering professional support and web based management of private and public packages,
-and granular access permissions. Private Packagist provides mirroring for packages' zip
-files which makes installs faster and independent from third party systems - e.g.
-you can deploy even if GitHub is down because your zip files are mirrored.
-
-Private Packagist is available as a hosted SaaS solution or as an on-premise self-hosted
-package, providing an easy interactive set up experience.
-
-Some of Private Packagist's revenue is used to pay for Composer and Packagist.org
-development and hosting so using it is a good way to support the maintenance of
-these open source projects financially. You can find more information about how to
-set up your own package archive on [Packagist.com](https://packagist.com).
-
-# Satis
-
-Satis on the other hand is open source but only a static `composer` repository
-generator. It is a bit like an ultra-lightweight, static file-based version of
-packagist and can be used to host the metadata of your company's private
-packages, or your own. You can get it from
-[GitHub](https://github.com/composer/satis) or install via CLI:
-
-    php composer.phar create-project composer/satis --stability=dev --keep-vcs
-
-## Setup
-
-For example let's assume you have a few packages you want to reuse across your
-company but don't really want to open-source. You would first define a Satis
-configuration: a json file with an arbitrary name that lists your curated
-[repositories](../05-repositories.md).
-
-Here is an example configuration, you see that it holds a few VCS repositories,
-but those could be any types of [repositories](../05-repositories.md). Then it
-uses `"require-all": true` which selects all versions of all packages in the
-repositories you defined.
-
-The default file Satis looks for is `satis.json` in the root of the repository.
-
-```json
-{
-  "name": "My Repository",
-  "homepage": "http://packages.example.org",
-  "repositories": [
-    { "type": "vcs", "url": "https://github.com/mycompany/privaterepo" },
-    { "type": "vcs", "url": "http://svn.example.org/private/repo" },
-    { "type": "vcs", "url": "https://github.com/mycompany/privaterepo2" }
-  ],
-  "require-all": true
-}
-```
-
-If you want to cherry pick which packages you want, you can list all the
-packages you want to have in your satis repository inside the classic composer
-`require` key, using a `"*"` constraint to make sure all versions are selected,
-or another constraint if you want really specific versions.
-
-```json
-{
-  "repositories": [
-    { "type": "vcs", "url": "https://github.com/mycompany/privaterepo" },
-    { "type": "vcs", "url": "http://svn.example.org/private/repo" },
-    { "type": "vcs", "url": "https://github.com/mycompany/privaterepo2" }
-  ],
-  "require": {
-    "company/package": "*",
-    "company/package2": "*",
-    "company/package3": "2.0.0"
-  }
-}
-```
-
-Once you've done this, you run:
-
-    php bin/satis build <configuration file> <build dir>
-
-When you ironed out that process, what you would typically do is run this
-command as a cron job on a server. It would then update all your package info
-much like Packagist does.
-
-Note that if your private packages are hosted on GitHub, your server should
-have an ssh key that gives it access to those packages, and then you should add
-the `--no-interaction` (or `-n`) flag to the command to make sure it falls back
-to ssh key authentication instead of prompting for a password. This is also a
-good trick for continuous integration servers.
-
-Set up a virtual-host that points to that `web/` directory, let's say it is
-`packages.example.org`. Alternatively, with PHP >= 5.4.0, you can use the
-built-in CLI server `php -S localhost:port -t satis-output-dir/` for a
-temporary solution.
-
-### Partial Updates
-
-You can tell Satis to selectively update only particular packages or process
-only a repository with a given URL. This cuts down the time it takes to rebuild
-the `package.json` file and is helpful if you use (custom) webhooks to trigger
-rebuilds whenever code is pushed into one of your repositories.
-
-To rebuild only particular packages, pass the package names on the command line
-like so:
-
-    php bin/satis build satis.json web/ this/package that/other-package
-
-Note that this will still need to pull and scan all of your VCS repositories
-because any VCS repository might contain (on any branch) one of the selected
-packages.
-
-If you want to scan only a single repository and update all packages found in
-it, pass the VCS repository URL as an optional argument:
-
-    php bin/satis build --repository-url https://only.my/repo.git satis.json web/
-
-## Usage
-
-In your projects all you need to add now is your own composer repository using
-the `packages.example.org` as URL, then you can require your private packages
-and everything should work smoothly. You don't need to copy all your
-repositories in every project anymore. Only that one unique repository that
-will update itself.
-
-```json
-{
-  "repositories": [ { "type": "composer", "url": "http://packages.example.org/" } ],
-  "require": {
-    "company/package": "1.2.0",
-    "company/package2": "1.5.2",
-    "company/package3": "dev-master"
-  }
-}
-```
-
-### Security
-
-To secure your private repository you can host it over SSH or SSL using a client
-certificate. In your project you can use the `options` parameter to specify the
-connection options for the server.
-
-Example using a custom repository using SSH (requires the SSH2 PECL extension):
-
-```json
-{
-  "repositories": [{
-    "type": "composer",
-    "url": "ssh2.sftp://example.org",
-    "options": {
-      "ssh2": {
-        "username": "composer",
-        "pubkey_file": "/home/composer/.ssh/id_rsa.pub",
-        "privkey_file": "/home/composer/.ssh/id_rsa"
-      }
-    }
-  }]
-}
-```
-
-> **Tip:** See [ssh2 context options] for more information.
-
-Example using SSL/TLS (HTTPS) using a client certificate:
-
-```json
-{
-  "repositories": [{
-     "type": "composer",
-     "url": "https://example.org",
-     "options": {
-       "ssl": {
-         "local_cert": "/home/composer/.ssl/composer.pem"
-       }
-     }
-  }]
-}
-```
-
-> **Tip:** See [ssl context options] for more information.
-
-Example using a custom HTTP Header field for token authentication:
-
-```json
-{
-  "repositories": [{
-    "type": "composer",
-    "url": "https://example.org",
-    "options":  {
-      "http": {
-        "header": [
-          "API-TOKEN: YOUR-API-TOKEN"
-        ]
-      }
-    }
-  }]
-}
-```
-
-### Authentication
-
-When your private repositories are password protected, you can store the
-authentication details permanently.  The first time Composer needs to
-authenticate against some domain it will prompt you for a username/password and
-then you will be asked whether you want to store it.
-
-The storage can be done either globally in the `COMPOSER_HOME/auth.json` file
-(`COMPOSER_HOME` defaults to `~/.composer` or `%APPDATA%/Composer` on Windows)
-or also in the project directory directly sitting besides your composer.json.
-
-You can also configure these by hand using the config command if you need to
-configure a production machine to be able to run non-interactive installs. For
-example to enter credentials for example.org one could type:
-
-    composer config http-basic.example.org username password
-
-That will store it in the current directory's auth.json, but if you want it
-available globally you can use the `--global` (`-g`) flag.
-
-### Downloads
-
-When GitHub, GitLab or BitBucket repositories are mirrored on your local satis, the
-build process will include the location of the downloads these platforms make
-available. This means that the repository and your setup depend on the
-availability of these services.
-
-At the same time, this implies that all code which is hosted somewhere else (on
-another service or for example in Subversion) will not have downloads available
-and thus installations usually take a lot longer.
-
-To enable your satis installation to create downloads for all (Git, Mercurial
-and Subversion) your packages, add the following to your `satis.json`:
-
-``` json
-{
-  "archive": {
-    "directory": "dist",
-    "format": "tar",
-    "prefix-url": "https://amazing.cdn.example.org",
-    "skip-dev": true
-  }
-}
-```
-
-#### Options explained
-
- * `directory`: required, the location of the dist files (inside the
-   `output-dir`)
- * `format`: optional, `zip` (default) or `tar`
- * `prefix-url`: optional, location of the downloads, homepage (from
-   `satis.json`) followed by `directory` by default
- * `skip-dev`: optional, `false` by default, when enabled (`true`) satis will
-   not create downloads for branches
- * `absolute-directory`: optional, a _local_ directory where the dist files are
-   dumped instead of `output-dir`/`directory`
- * `whitelist`: optional, if set as a list of package names, satis will only
-   dump the dist files of these packages
- * `blacklist`: optional, if set as a list of package names, satis will not
-   dump the dist files of these packages
- * `checksum`: optional, `true` by default, when disabled (`false`) satis will
-   not provide the sha1 checksum for the dist files
-
-Once enabled, all downloads (include those from GitHub and BitBucket) will be
-replaced with a _local_ version.
-
-#### prefix-url
-
-Prefixing the URL with another host is especially helpful if the downloads end
-up in a private Amazon S3 bucket or on a CDN host. A CDN would drastically
-improve download times and therefore package installation.
-
-Example: A `prefix-url` of `https://my-bucket.s3.amazonaws.com` (and
-`directory` set to `dist`) creates download URLs which look like the following:
-`https://my-bucket.s3.amazonaws.com/dist/vendor-package-version-ref.zip`.
-
-### Web outputs
-
- * `output-html`: optional, `true` by default, when disabled (`false`) satis
-   will not generate the `output-dir`/index.html page.
- * `twig-template`: optional, a path to a personalized [Twig] template for
-   the `output-dir`/index.html page.
-
-### Abandoned packages
-
-To enable your satis installation to indicate that some packages are abandoned,
-add the following to your `satis.json`:
-
-```json
-{
-  "abandoned": {
-    "company/package": true,
-    "company/package2": "company/newpackage"
-  }
-}
-```
-
-The `true` value indicates that the package is truly abandoned while the
-`"company/newpackage"` value specifies that the package is replaced by the
-`company/newpackage` package.
-
-Note that all packages set as abandoned in their own `composer.json` file will
-be marked abandoned as well.
-
-### Resolving dependencies
-
-It is possible to make satis automatically resolve and add all dependencies for
-your projects. This can be used with the Downloads functionality to have a
-complete local mirror of packages. Add the following to your `satis.json`:
-
-```json
-{
-  "require-dependencies": true,
-  "require-dev-dependencies": true
-}
-```
-
-When searching for packages, satis will attempt to resolve all the required
-packages from the listed repositories.  Therefore, if you are requiring a
-package from Packagist, you will need to define it in your `satis.json`.
-
-Dev dependencies are packaged only if the `require-dev-dependencies` parameter
-is set to true.
-
-### Other options
-
- * `providers`: optional, `false` by default, when enabled (`true`) each
-   package will be dumped into a separate include file which will be only
-   loaded by composer when the package is really required. Speeds up composer
-   handling for repositories with huge number of packages like f.i. packagist.
- * `output-dir`: optional, defines where to output the repository files if not
-   provided as an argument when calling the `build` command.
- * `config`: optional, lets you define all config options from composer, except
-   `archive-format` and `archive-dir` as the configuration is done through
-   [archive](#downloads) instead. See docs on [config schema] for more details.
- * `notify-batch`: optional, specify a URL that will be called every time a
-   user installs a package. See [notify-batch].
-
-[ssh2 context options]: https://secure.php.net/manual/en/wrappers.ssh2.php#refsect1-wrappers.ssh2-options
-[ssl context options]: https://secure.php.net/manual/en/context.ssl.php
-[Twig]: https://twig.sensiolabs.org/
-[config schema]: https://getcomposer.org/doc/04-schema.md#config
-[notify-batch]: https://getcomposer.org/doc/05-repositories.md#notify-batch