dependabot-composer 0.111.16 → 0.111.17

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

@@ -0,0 +1,204 @@
+<!--
+    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

@@ -0,0 +1,343 @@
+<!--
+    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