From 93e8608353010dda3e16bf6bcb200334fbe08cdf Mon Sep 17 00:00:00 2001
From: Igor Benko <i.benko@packagist.com>
Date: Tue, 9 Dec 2025 12:24:38 +0100
Subject: [PATCH 1/2] Use composer api to retrieve the package metadata

---
 docs/api/package-metadata.md | 41 ++++++++++++++++++++++++++++++++++++
 1 file changed, 41 insertions(+)
 create mode 100644 docs/api/package-metadata.md

diff --git a/docs/api/package-metadata.md b/docs/api/package-metadata.md
new file mode 100644
index 0000000..6d79283
--- /dev/null
+++ b/docs/api/package-metadata.md
@@ -0,0 +1,41 @@
+# Reading package metadata via API
+
+To read the package metadata via API, use the Composer API on your Private Packagist repository.
+
+Read more about the API: https://packagist.org/apidoc#get-package-data
+
+### Example implementation
+
+```bash
+# Make sure the composer/metadata-minifer package is installed:
+composer require composer/metadata-minifier
+```
+
+```php
+use Composer\MetadataMinifier\MetadataMinifier;
+
+// Assuming your organization name is acme-company and the package name is acme/package
+$organization = 'acme-company'; 
+$package = 'acme/package'; 
+
+// NOTE: You must use an authentication token for the composer API, not the Private Packagist API credentials.
+// You can create a token in your Organization settings > Authentication Tokens
+$token = 'packagist_ort_..........'; 
+
+$apiUrl = sprintf('https://repo.packagist.com/%s/p2/%s.json', $organization, $package); 
+
+$ch = curl_init($apiUrl); 
+curl_setopt_array($ch, [ 
+    CURLOPT_RETURNTRANSFER => true, 
+    CURLOPT_HTTPAUTH => CURLAUTH_BASIC, 
+    CURLOPT_USERPWD => 'token:' . $token
+]); 
+
+$response = curl_exec($ch); 
+curl_close($ch); 
+
+$data = json_decode($response, true); 
+$metadata = MetadataMinifier::expand($data['packages'][$package]);
+```
+
+

From 34adee0b5116ea1ce3a6796bef38b2cb2f430c3c Mon Sep 17 00:00:00 2001
From: Igor Benko <i.benko@packagist.com>
Date: Mon, 15 Dec 2025 09:25:34 +0100
Subject: [PATCH 2/2] Extend docs for retrieving the package metadata

---
 docs/api/package-metadata.md | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/docs/api/package-metadata.md b/docs/api/package-metadata.md
index 6d79283..a12a7c4 100644
--- a/docs/api/package-metadata.md
+++ b/docs/api/package-metadata.md
@@ -2,10 +2,20 @@
 
 To read the package metadata via API, use the Composer API on your Private Packagist repository.
 
+This is useful when you need to programmatically access package metadata beyond what's available through the Private Packagist API
+(for example to read custom configuration from the `extra` section of a package's composer.json). 
+
 Read more about the API: https://packagist.org/apidoc#get-package-data
 
+
 ### Example implementation
 
+The process works as follows:
+1. Get the JSON from `https://repo.packagist.com/<org>/p2/<package>.json`
+2. Authenticate using username `token` and an Authentication Token as password
+3. Decode the JSON as nested arrays
+4. Use [MetadataMinifier](https://github.com/composer/metadata-minifier) to expand the metadata for each package version: `$metadata = MetadataMinifier::expand($data['packages'][$package])`
+
 ```bash
 # Make sure the composer/metadata-minifer package is installed:
 composer require composer/metadata-minifier
@@ -22,6 +32,8 @@ $package = 'acme/package';
 // You can create a token in your Organization settings > Authentication Tokens
 $token = 'packagist_ort_..........'; 
 
+// The p2/$vendor/$package.json endpoint contains only tagged releases. If you want to fetch information about branches (i.e. dev versions) 
+// you need to use p2/$vendor/$package~dev.json.
 $apiUrl = sprintf('https://repo.packagist.com/%s/p2/%s.json', $organization, $package); 
 
 $ch = curl_init($apiUrl);