Merge branch '15886-composer-docs' into 'master'

PHP Composer docs

Closes #15886

See merge request gitlab-org/gitlab!32623

doc/administration/geo/replication/datatypes.md

@@ -147,6 +147,7 @@ successfully, you must replicate their data using some other means.
 | [Conan Repository](../../../user/packages/conan_repository/index.md) | [No](https://gitlab.com/groups/gitlab-org/-/epics/2346)  | No                                                      |                                                                                                            |
 | [NuGet Repository](../../../user/packages/nuget_repository/index.md) | [No](https://gitlab.com/groups/gitlab-org/-/epics/2346)  | No                                                      |                                                                                                            |
 | [PyPi Repository](../../../user/packages/pypi_repository/index.md)   | [No](https://gitlab.com/groups/gitlab-org/-/epics/2554)  | No                                                      |                                                                                                            |
+| [Composer Repository](../../../user/packages/composer_repository/index.md) | [No](https://gitlab.com/groups/gitlab-org/-/epics/3096)  | No                                                      |                                                                                                            |
 | [External merge request diffs](../../merge_request_diffs.md)         | [No](https://gitlab.com/gitlab-org/gitlab/-/issues/33817)  | No                                                      |                                           |
 | [Terraform State](../../terraform_state.md)                                                                  | [No](https://gitlab.com/groups/gitlab-org/-/epics/3112)(*3*) | No                                                        |                                                                                                            |
 | [Vulnerability Export](../../../user/application_security/security_dashboard/#export-vulnerabilities-1)      | [No](https://gitlab.com/groups/gitlab-org/-/epics/3111)(*3*) | No                                                        |                                                                                                            |                                                                                                            |

doc/administration/packages/index.md

@@ -15,6 +15,7 @@ The Packages feature allows GitLab to act as a repository for the following:
 | Software repository | Description | Available in GitLab version |
 | ------------------- | ----------- | --------------------------- |
 | [PyPi Repository](../../user/packages/pypi_repository/index.md) | The GitLab PyPi Repository enables every project in GitLab to have its own space to store [PyPi](https://pypi.org/) packages. | 12.10+ |
+| [Composer Repository](../../user/packages/composer_repository/index.md) | The GitLab Composer Repository enables every project in GitLab to have its own space to store [Composer](https://getcomposer.org/) packages. | 13.1+ |
 | [NuGet Repository](../../user/packages/nuget_repository/index.md) | The GitLab NuGet Repository enables every project in GitLab to have its own space to store [NuGet](https://www.nuget.org/) packages. | 12.8+ |
 | [Conan Repository](../../user/packages/conan_repository/index.md) | The GitLab Conan Repository enables every project in GitLab to have its own space to store [Conan](https://conan.io/) packages. | 12.4+ |
 | [Maven Repository](../../user/packages/maven_repository/index.md) | The GitLab Maven Repository enables every project in GitLab to have its own space to store [Maven](https://maven.apache.org/) packages. | 11.3+ |

doc/api/packages.md

@@ -20,7 +20,7 @@ GET /projects/:id/packages
 | `id`      | integer/string | yes | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
 | `order_by`| string | no | The field to use as order. One of `created_at` (default), `name`, `version`, or `type`. |
 | `sort`    | string | no | The direction of the order, either `asc` (default) for ascending order or `desc` for descending order. |
-| `package_type` | string | no | Filter the returned packages by type. One of `conan`, `maven`, `npm`, `pypi` or `nuget`. (_Introduced in GitLab 12.9_)
+| `package_type` | string | no | Filter the returned packages by type. One of `conan`, `maven`, `npm`, `pypi`, `composer`, or `nuget`. (_Introduced in GitLab 12.9_)
 | `package_name` | string | no | Filter the project packages with a fuzzy search by name. (_Introduced in GitLab 12.9_)
 
 ```shell
@@ -67,7 +67,7 @@ GET /groups/:id/packages
 | `exclude_subgroups` | boolean | false | If the parameter is included as true, packages from projects from subgroups are not listed. Default is `false`. |
 | `order_by`| string | no | The field to use as order. One of `created_at` (default), `name`, `version`, `type`, or `project_path`. |
 | `sort`    | string | no | The direction of the order, either `asc` (default) for ascending order or `desc` for descending order. |
-| `package_type` | string | no | Filter the returned packages by type. One of `conan`, `maven`, `npm`, `pypi` or `nuget`. (_Introduced in GitLab 12.9_) |
+| `package_type` | string | no | Filter the returned packages by type. One of `conan`, `maven`, `npm`, `pypi`, `composer`, or `nuget`. (_Introduced in GitLab 12.9_) |
 | `package_name` | string | no | Filter the project packages with a fuzzy search by name. (_[Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/30980) in GitLab 13.0_)
 
 ```shell

doc/development/packages.md

@@ -66,11 +66,14 @@ The current state of existing package registries availability is:
 | NuGet           | Yes | No - [open issue](https://gitlab.com/gitlab-org/gitlab/-/issues/36423) | No |
 | PyPI            | Yes | No | No |
 | Go              | Yes | No - [open issue](https://gitlab.com/gitlab-org/gitlab/-/issues/213900) | No - [open-issue](https://gitlab.com/gitlab-org/gitlab/-/issues/213902) |
+| Composer | Yes | Yes | No |
 
 NOTE: **Note:** NPM is currently a hybrid of the instance level and group level.
 It is using the top-level group or namespace as the defining portion of the name
 (for example, `@my-group-name/my-package-name`).
 
+**Note:** Composer package naming scope is Instance Level.
+
 ### Naming conventions
 
 To avoid name conflict for instance-level endpoints you will need to define a package naming convention

doc/user/packages/composer_repository/index.md

+# GitLab Composer Repository **(PREMIUM)**
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15886) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.1.
+
+With the GitLab Composer Repository, every project can have its own space to store [Composer](https://getcomposer.org/) packages.
+
+## Enabling the Composer Repository
+
+NOTE: **Note:**
+This option is available only if your GitLab administrator has
+[enabled support for the Package Registry](../../../administration/packages/index.md). **(PREMIUM ONLY)**
+
+After the Composer Repository is enabled, it will be available for all new projects
+by default. To enable it for existing projects, or if you want to disable it:
+
+1. Navigate to your project's **Settings > General > Permissions**.
+1. Find the Packages feature and enable or disable it.
+1. Click on **Save changes** for the changes to take effect.
+
+You should then be able to see the **Packages & Registries** section on the left sidebar.
+
+## Getting started
+
+This section will cover creating a new example Composer package to publish. This is a
+quickstart to test out the **GitLab Composer Registry**.
+
+You will need a recent version of [Composer](https://getcomposer.org/).
+
+### Creating a package project
+
+Understanding how to create a full Composer project is outside the scope of this
+guide, but you can create a small package to test out the registry. Start by
+creating a new directory called `my-composer-package`:
+
+```shell
+mkdir my-composer-package && cd my-composer-package
+```
+
+Create a new `composer.json` file inside this directory to set up the basic project:
+
+```shell
+touch composer.json
+```
+
+Inside `composer.json`, add the following code:
+
+```json
+{
+  "name": "<namespace>/composer-test",
+  "type": "library",
+  "license": "GPL-3.0-only",
+  "version": "1.0.0"
+}
+```
+
+Replace `<namespace>` with a unique namespace like your GitLab username or group name.
+
+After this basic package structure is created, we need to tag it in Git and push it to the repository.
+
+```shell
+git init
+add composer.json
+git commit -m 'Composer package test'
+git tag v1.0.0
+git add origin git@gitlab.com:<namespace>/<project-name>.git
+git push origin v1.0.0
+```
+
+### Publishing the package
+
+Now that the basics of our project is completed, we can publish the package.
+For accomplishing this you will need the following:
+
+- A personal access token. You can generate a [personal access token](../../../user/profile/personal_access_tokens.md) with the scope set to `api` for repository authentication.
+- Your project ID which can be found on the home page of your project.
+
+To publish the package hosted on GitLab we'll need to make a `POST` to the GitLab package API using a tool like `curl`:
+
+```shell
+curl --data tag=<tag> 'https://__token__:<personal-access-token>@gitlab.com/api/v4/projects/<project_id>/packages/composer'
+```
+
+Where:
+
+- `<personal-access-token>` is your personal access token.
+- `<project_id>` is your project ID.
+- `<tag>` is the Git tag name of the version you want to publish. In this example it should be `v1.0.0`. Notice that instead of `tag=<tag>` you can also use `branch=<branch>` to publish branches.
+
+If the above command succeeds, you now should be able to see the package under the **Packages & Registries** section of your project page.
+
+### Installing a package
+
+To install your package you will need:
+
+- A personal access token. You can generate a [personal access token](../../../user/profile/personal_access_tokens.md) with the scope set to `api` for repository authentication.
+- Your group ID which can be found on the home page of your project's group.
+
+Add the GitLab Composer package repository to your existing project's `composer.json` file, along with the package name and version you want to install like so:
+
+```json
+{
+  ...
+  "repositories": [
+    { "type": "composer", "url": "https://gitlab.com/api/v4/group/<group_id>/-/packages/composer/packages.json" }
+  ],
+  "require": {
+    ...
+    "<package_name>": "<version>"
+  },
+  ...
+}
+```
+
+Where:
+
+- `<group_id>` is the group ID found under your project's group page.
+- `<package_name>` is your package name as defined in your package's `composer.json` file.
+- `<version>` is your package version (`1.0.0` in this example).
+
+You will also need to create a `auth.json` file with your GitLab credentials:
+
+```json
+{
+    "http-basic": {
+        "gitlab.com": {
+            "username": "___token___",
+            "password": "<personal_access_token>"
+        }
+    }
+}
+```
+
+Where:
+
+- `<personal_access_token>` is your personal access token.
+
+With the `composer.json` and `auth.json` files configured, you can install the package by running `composer`:
+
+```shell
+composer update
+```
+
+If successful, you should be able to see the output indicating that the package has been successfully installed.

doc/user/packages/index.md

@@ -22,6 +22,7 @@ The Packages feature allows GitLab to act as a repository for the following:
 | [NuGet Repository](nuget_repository/index.md) **(PREMIUM)**  | The GitLab NuGet Repository will enable every project in GitLab to have its own space to store [NuGet](https://www.nuget.org/) packages. | 12.8+ |
 | [PyPi Repository](pypi_repository/index.md) **(PREMIUM)**  | The GitLab PyPi Repository will enable every project in GitLab to have its own space to store [PyPi](https://pypi.org/) packages. | 12.10+ |
 | [Go Proxy](go_proxy/index.md) **(PREMIUM)** | The Go proxy for GitLab enables every project in GitLab to be fetched with the [Go proxy protocol](https://proxy.golang.org/). | 13.1+ |
+| [Composer Repository](composer_repository/index.md) **(PREMIUM)**  | The GitLab Composer Repository will enable every project in GitLab to have its own space to store [Composer](https://getcomposer.org/) packages. | 13.1+ |
 
 ## Enable the Package Registry for your project