> For the complete documentation index, see [llms.txt](https://developer.harness.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.harness.io/artifact-registry/3.0/setup/php-composer.md).

# PHP Composer

PHP Composer - host PHP packages in Harness Artifacts

Use a **PHP Composer** registry to host private PHP packages. The registry works with the Composer CLI.

## What you will learn from this topic

By the end of this guide, you will know how to:

* Create a registry in Harness Artifacts.
* Publish a package to the registry.
* Install the package from the registry and confirm that it works.

## Before you begin

* Install the Composer CLI (`composer`) on your local machine.
* Install the Harness CLI (`hc`). You use it to publish packages to your registry.
* Make sure you have access to a Harness account with permission to create registries and connectors.

## Create a PHP Composer registry

To create a PHP Composer registry:

1. In Artifact Registry, select **Registries**.
2. Select **+ Create Registry**.
3. Specify the **Registry name**.

{% hint style="info" %}
**Registry name criteria**

The registry name must start with a letter, can only contain lowercase alphanumerics, `_`, `.`, and `-`, and must be unique to your Harness account.
{% endhint %}

4. Optionally, add a **Description**.
5. Choose visibility between **Public** and **Private**. The default is *Private*.
6. Select **Composer** as the **Registry type**.
7. Click **Save**.
8. Select **Create** to finalize.

## Configure an upstream proxy (optional)

An upstream proxy allows your registry to fetch PHP Composer packages from an external source when they are not available locally. The default upstream is Packagist.

### Create upstream proxy

To create an upstream proxy:

1. In Artifact Registry, select **Registries**.
2. Select the drop-down next to **+ Create Registry** and select **Upstream Proxy**.
3. Specify the **Registry name**.
4. Optionally, add a **Description**.
5. Choose visibility between **Public** and **Private**. The default is *Private*.
6. Select **Composer** as the **Registry type**.
7. Select the **Source**: **Packagist** or **Custom**.
   * If you select **Custom**, specify the **Remote registry URL**.

{% hint style="info" %}
**V1 repository support**

If your external source is a Composer v1 repository, select **Custom** as the **Source**, then enter the v1 repository URL as the **Remote registry URL**.
{% endhint %}

8. Select the **Authentication method**.
   * **Username and password**: Specify the username and password. Use an existing secret, or create a new secret by specifying the **Name** and entering the **Secret text**.
   * **Anonymous**: No credentials required. This works for public Composer sources.
9. Optionally, configure **Metadata configuration** to control how long the registry caches metadata and not-found responses from the upstream source.

{% hint style="info" %}
**Metadata configuration**

The **Metadata cache TTL (seconds)** field controls how long cached metadata, such as a package index, stays valid before the registry fetches it again. The **Negative cache TTL (seconds)** field controls how long the registry caches a not-found response, so it does not repeat an upstream lookup for a package it already failed to find. Both fields accept a value from 0 to 604800 seconds (7 days) and default to 600 seconds (10 minutes); a value of 0 is treated as unset.

Metadata TTL does not remove cached artifacts. To delete cached artifacts, go to [Lifecycle Management overview](https://developer.harness.io/artifact-registry/3.0/lifecycle-management/overview.md).

For the full field reference, go to [Configure metadata cache TTL](https://developer.harness.io/artifact-registry/3.0/registries/create-an-upstream-proxy.md#configure-metadata-cache-ttl).
{% endhint %}

10. Select **Create** to finalize.

### Configure the upstream proxy in your registry

To configure the upstream proxy in your registry:

1. In Artifact Registry, select an existing PHP Composer Artifact.
2. Navigate to the **Configuration** tab.
3. Select **Edit** in the **Upstream proxy** section.
4. Click **+ Add upstream proxy**.
5. Select the required proxy from the list.
6. Click **Apply**.
7. Select **Update** to finalize.

{% hint style="info" %}
**Upstream proxy caching**

If a package is not found in your Harness registry, the upstream proxy fetches it from Packagist or your custom source and caches it.
{% endhint %}

## PHP Composer client setup

In your PHP Composer Artifact, select the registry, then select **Setup Client**. The dialog gives you an identity token, then setup instructions for the Composer client.

### Generate an identity token

An identity token serves as the password for authenticating with the registry.

1. In your PHP Composer Artifact, select **Setup Client**.
2. Select **Generate Token**.
3. Select an **Expiration** for the token:
   * **30 Days**
   * **90 Days**
   * **180 Days**
   * **Custom**
4. Copy the token. You use it in the following steps in place of `<IDENTITY_TOKEN>`.

{% hint style="info" %}
**Token expiration**

The identity token stops working after the expiration you select. Generate a new token and update your client configuration before the current token expires.
{% endhint %}

### Configure the client

In the code samples, replace the values in angle brackets with your own values.

**1. Configure authentication**

Configure Composer to use the identity token for authentication:

```bash
composer config --global --auth http-basic.pkg.harness.io token <IDENTITY_TOKEN>
```

**2. Publish a package**

Create a Composer archive from your project:

```bash
composer archive --format=zip
```

Upload the archive to the registry using the Harness CLI:

```bash
hc artifact push composer <REGISTRY_NAME> <FILE_PATH> --pkg-url pkg.harness.io
```

**3. Install a package**

Add the registry to your project's `composer.json`:

```json
"repositories": [
  {
    "type": "composer",
    "url": "https://pkg.harness.io/pkg/<ACCOUNT_ID>/<REGISTRY_NAME>/composer"
  }
]
```

Install the package:

```bash
composer require <ARTIFACT_NAME>:<VERSION>
```

## Setup verification

Confirm that your registry serves the package you published. To verify your setup:

1. In a new project with no cached dependencies for the package, meaning no matching entries in your Composer cache directory (`~/.composer/cache` or `$COMPOSER_HOME/cache`), use Composer to install the package you published.
2. Confirm that the client downloaded the package from your Harness registry address, which is shown in **Setup Client**.
3. In Harness, open your registry and confirm that the package and version appear in the package list.

If a step fails, go to [Troubleshooting](#troubleshooting) to resolve common authentication and resolution issues before you retry.

## Pipeline automation (optional)

Publishing from a pipeline gives you a repeatable release process. Run the publish step when you create a version tag, so each release maps to one version in the registry.

The following Run step shows the shape of a publish step for a PHP Composer package. Store the identity token as a Harness secret, and do not write it into the pipeline YAML.

```yaml
- step:
    type: Run
    name: Publish package
    identifier: publish_package
    spec:
      shell: Sh
      envVariables:
        PACKAGE_VERSION: <+codebase.tag>
      command: |
        composer config version "$PACKAGE_VERSION"
        composer archive --format=zip
        hc artifact push composer <REGISTRY_NAME> ./*.zip --pkg-url pkg.harness.io
```

## Troubleshooting

<details>

<summary>`composer config` or `composer require` fails with `401` or `403` against a PHP Composer registry</summary>

Check that the registry address in your Composer configuration matches the one shown in **Setup Client**, and that the identity token is the one you generated there. If the token has expired or was revoked, generate a new one and update your client configuration.

</details>

<details>

<summary>`hc artifact push composer` returns `409 Conflict`</summary>

Package versions are immutable after publish. Choose a new version, or delete the existing version only if your registry retention and lifecycle policies allow it.

</details>

<details>

<summary>`composer require` cannot find a package, or resolves only the latest version</summary>

Check that the package name and version match the values you used when you published the package. Also, check that the registry name and account ID in your `composer.json` repository entry are correct.

</details>

<details>

<summary>Composer uses a cached version after a new publish</summary>

Clear the Composer cache (`composer clear-cache`), and update the version you pinned in your `composer.json`.

</details>

<details>

<summary>**Setup Client** has no publish instructions on an upstream proxy registry</summary>

An upstream proxy registry is pull-only, so **Setup Client** omits the publish instructions for it. Publish to a virtual PHP Composer registry instead, or cache packages from Packagist through the upstream proxy.

</details>

## Next steps

* To add a pipeline that publishes a new version for every release tag, go to [Harness CI](https://developer.harness.io/artifact-registry/3.0/platform-integrations/harness-ci.md).
* To control who can publish and consume packages in your registry, go to [RBAC and permissions](https://developer.harness.io/artifact-registry/3.0/reference/rbac-and-permissions.md).
* To set retention and lifecycle rules for old versions, go to [Lifecycle Management overview](https://developer.harness.io/artifact-registry/3.0/lifecycle-management/overview.md).

{% @harness-feedback/feedback %}
