Add options to configure repository priorities

doc/05-repositories.md

@@ -41,7 +41,7 @@ be preferred.
 A repository is a package source. It's a list of packages/versions. Composer
 will look in all your repositories to find the packages your project requires.
 
-By default only the Packagist repository is registered in Composer. You can
+By default only the Packagist.org repository is registered in Composer. You can
 add more repositories to your project by declaring them in `composer.json`.
 
 Repositories are only available to the root package and the repositories
@@ -49,6 +49,12 @@ defined in your dependencies will not be loaded. Read the
 [FAQ entry](faqs/why-can't-composer-load-repositories-recursively.md) if you
 want to learn why.
 
+When resolving dependencies, packages are looked up from repositories from
+top to bottom, and by default as soon as a package is found in one Composer
+stops looking in other repositories. Read the
+[repository priorities](articles/repository-priorities.md) article for more
+details and to see how to change this behavior.
+
 ## Types
 
 ### Composer
@@ -62,6 +68,17 @@ In the case of packagist, that file is located at `/packages.json`, so the URL o
 the repository would be `repo.packagist.org`. For `example.org/packages.json` the
 repository URL would be `example.org`.
 
+```json
+{
+    "repositories": [
+        {
+            "type": "composer",
+            "url": "https://example.org"
+        }
+    ]
+}
+```
+
 #### packages
 
 The only required field is `packages`. The JSON structure is as follows:

doc/articles/repository-priorities.md

@@ -0,0 +1,94 @@
+<!--
+    tagline: Configure which packages are found in which repositories
+-->
+
+# Repository priorities
+
+## Canonical repositories
+
+When Composer resolves dependencies it will look up a given package in the
+topmost repository. If that repository does not contain the package, it
+goes on to the next one, until one repository contains it and the process ends.
+
+Canonical repositories are better for a few reasons:
+
+- Performance wise, it is more efficient to stop looking for a package once it
+has been found somewhere. It also avoids loading duplicate packages in case
+the same package is present in several of your repositories.
+- Security wise, it is safer to treat them canonically as it means that your most
+important repositories will return the packages you expect them to always. Let's
+say you have a private repository which is not canonical, and you require your
+private package `foo/bar ^2.0` for example. Now if someone publishes
+`foo/bar 2.999` to packagist.org, suddenly Composer will pick that package as it
+has a higher version than your latest release (say 2.4.3), and you end up install
+something you may not have meant to. If the private repository is canonical
+however, that 2.999 version from packagist.org will not be considered at all.
+
+There are however a few cases where you may want to specifically load some packages
+from a given repository, but not all. Or you may want a given repository to not be
+canonical, and to be only preferred if it has higher package versions than the
+repositories defined below.
+
+## Default behavior
+
+By default in Composer 2.x all repositories are canonical. Composer 1.x treated
+all repositories as non-canonical.
+
+Another default is that the packagist.org repository is always added implicitly
+as the last repository, unless you [disable it](../05-repositories.md#disabling-packagist-org).
+
+## Making repositories non-canonical
+
+You can add the canonical option to any repository to disable this default behavior
+and make sure Composer keeps looking in other repositories, even if that repository
+contains a given package.
+
+```json
+{
+    "repositories": [
+        {
+            "type": "composer",
+            "url": "https://example.org",
+            "canonical": false
+        }
+    ]
+}
+```
+
+## Filtering packages
+
+You can also filter packages which a repository will be able to load, either by
+selecting which you want, or by excluding those you do not want.
+
+For example here we want to pick only the `foo/bar` and all the packages from
+`some-vendor/` from this composer repository.
+
+```json
+{
+    "repositories": [
+        {
+            "type": "composer",
+            "url": "https://example.org",
+            "only": ["foo/bar", "some-vendor/*"]
+        }
+    ]
+}
+```
+
+And in this other example we exclude `toy/package` from a path repository, which
+we may not want to load in this project.
+
+```json
+{
+    "repositories": [
+        {
+            "type": "composer",
+            "url": "https://example.org",
+            "exclude": ["toy/package"]
+        }
+    ]
+}
+```
+
+Both `only` and `exclude` should be array of package names, which can also
+contain wildcards (`*`) which will match any characters.