Skip to content

Commit 159351b

Browse files
Copilotclemensv
Copilot
and
clemensv
authored
Add PHP SDK publish workflow for Packagist (#16)
* Initial plan * Add PHP SDK publish workflow for Packagist Co-authored-by: clemensv <542030+clemensv@users.noreply.github.com> * Improve Packagist API error handling in publish workflow Co-authored-by: clemensv <542030+clemensv@users.noreply.github.com> --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: clemensv <542030+clemensv@users.noreply.github.com>
1 parent b8cd0f6 commit 159351b

2 files changed

Lines changed: 202 additions & 0 deletions

File tree

‎.github/workflows/php.yml‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -57,3 +57,41 @@ jobs:
5757
file: php/coverage.xml
5858
flags: php
5959
fail_ci_if_error: false
60+
61+
publish:
62+
name: Publish to Packagist
63+
runs-on: ubuntu-latest
64+
needs: test
65+
if: startsWith(github.ref, 'refs/tags/v')
66+
67+
steps:
68+
- uses: actions/checkout@v4
69+
with:
70+
submodules: recursive
71+
72+
- name: Extract version from tag
73+
id: get_version
74+
run: |
75+
VERSION=${GITHUB_REF#refs/tags/v}
76+
echo "VERSION=$VERSION" >> $GITHUB_OUTPUT
77+
echo "Extracted version: $VERSION"
78+
79+
- name: Trigger Packagist update
80+
run: |
81+
response=$(curl -X POST \
82+
--fail-with-body \
83+
-H "Content-Type: application/json" \
84+
-w "\nHTTP_CODE:%{http_code}" \
85+
"https://packagist.org/api/update-package?username=${{ secrets.PACKAGIST_USERNAME }}&apiToken=${{ secrets.PACKAGIST_API_TOKEN }}" \
86+
-d '{"repository":{"url":"https://github.com/json-structure/sdk"}}')
87+
88+
echo "$response"
89+
90+
http_code=$(echo "$response" | \
91+
grep -o "HTTP_CODE:[0-9]*" | cut -d: -f2)
92+
if [ "$http_code" != "200" ] && [ "$http_code" != "202" ]; then
93+
echo "Error: Packagist API returned HTTP $http_code"
94+
exit 1
95+
fi
96+
97+
echo "Successfully triggered Packagist update (HTTP $http_code)"

‎php/PUBLISHING.md‎

Lines changed: 164 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,164 @@
1+
# Publishing to Packagist
2+
3+
This document describes how to publish the PHP SDK to Packagist.
4+
5+
## Prerequisites
6+
7+
### 1. Packagist Account
8+
9+
Create an account at https://packagist.org/
10+
11+
Packagist is the main Composer repository for PHP packages. You'll need an account to register and manage packages.
12+
13+
### 2. Register Package on Packagist
14+
15+
1. Log in to https://packagist.org/
16+
2. Go to "Submit" or "Submit Package"
17+
3. Enter the GitHub repository URL: `https://github.com/json-structure/sdk`
18+
4. Submit the package
19+
20+
### 3. Generate Packagist API Token
21+
22+
1. Go to your Packagist profile settings
23+
2. Navigate to "API Token" section
24+
3. Generate a new API token with "Update" permission
25+
4. Copy the token - you'll need it for GitHub secrets
26+
27+
### 4. GitHub Secrets
28+
29+
Configure these secrets in your repository settings (Settings → Secrets and variables → Actions):
30+
31+
- `PACKAGIST_USERNAME`: Your Packagist username
32+
- `PACKAGIST_API_TOKEN`: Your Packagist API token (from step 3)
33+
34+
## Automated Release Process
35+
36+
The CI workflow automatically notifies Packagist when you push a version tag.
37+
38+
### Creating a Release
39+
40+
1. Ensure all tests pass on the main branch
41+
2. Create and push a version tag:
42+
43+
```bash
44+
git tag v0.1.0
45+
git push origin v0.1.0
46+
```
47+
48+
### What Happens Automatically
49+
50+
The CI workflow will:
51+
52+
1. ✅ Run all tests across multiple PHP versions (8.1, 8.2, 8.3)
53+
2. ✅ Validate composer.json
54+
3. ✅ Extract version from the git tag
55+
4. ✅ Trigger Packagist update via API
56+
57+
### Tag Format
58+
59+
Tags must follow the pattern `v[0-9]+.[0-9]+.[0-9]+`:
60+
61+
- `v0.1.0` - Initial release
62+
- `v0.1.1` - Patch release
63+
- `v1.0.0` - Major release
64+
65+
## How Packagist Works
66+
67+
Packagist reads version information directly from your GitHub repository tags. You don't need to manually update the version in `composer.json` - Packagist automatically:
68+
69+
1. Detects git tags matching semantic versioning (e.g., `v1.0.0`, `1.0.0`)
70+
2. Creates corresponding package versions
71+
3. Makes them available via `composer require json-structure/sdk`
72+
73+
### Version Detection
74+
75+
When you push a tag like `v1.2.3`, Packagist will:
76+
- Create version `1.2.3` for users to install
77+
- Read package metadata from `composer.json` on that tagged commit
78+
- Make it installable via: `composer require json-structure/sdk:^1.2.3`
79+
80+
## Manual Trigger
81+
82+
If you need to manually trigger a Packagist update:
83+
84+
### Using the API
85+
86+
```bash
87+
curl -X POST \
88+
-H "Content-Type: application/json" \
89+
"https://packagist.org/api/update-package?username=YOUR_USERNAME&apiToken=YOUR_API_TOKEN" \
90+
-d '{"repository":{"url":"https://github.com/json-structure/sdk"}}'
91+
```
92+
93+
### Using the Web Interface
94+
95+
1. Log in to Packagist
96+
2. Go to your package page
97+
3. Click "Update" button to force a sync
98+
99+
## Verification
100+
101+
After publishing:
102+
103+
1. Check https://packagist.org/packages/json-structure/sdk
104+
2. Verify the new version appears in the versions list
105+
3. Test installation:
106+
107+
```bash
108+
composer require json-structure/sdk
109+
```
110+
111+
Or for a specific version:
112+
113+
```bash
114+
composer require json-structure/sdk:^0.1.0
115+
```
116+
117+
## Troubleshooting
118+
119+
### Package Not Updating
120+
121+
- Verify the GitHub webhook is configured (Packagist should set this automatically)
122+
- Manually trigger an update using the Packagist web interface
123+
- Check that the API credentials in GitHub secrets are correct
124+
125+
### Version Not Appearing
126+
127+
- Ensure your tag follows semantic versioning (e.g., `v1.0.0` or `1.0.0`)
128+
- Check that `composer.json` is valid: `composer validate --strict`
129+
- Wait a few minutes - Packagist may take time to index
130+
131+
### First-Time Setup
132+
133+
For the first publication:
134+
135+
1. Register the package on Packagist manually
136+
2. Packagist will set up a GitHub webhook automatically
137+
3. Subsequent updates will be automatic (or use the CI workflow)
138+
139+
## GitHub Webhook (Recommended)
140+
141+
For fully automatic updates without CI:
142+
143+
1. Packagist sets up a GitHub webhook when you register your package
144+
2. Every push to GitHub (including tags) triggers Packagist to re-index
145+
3. No manual intervention or API calls needed
146+
147+
To verify the webhook:
148+
1. Go to your GitHub repo → Settings → Webhooks
149+
2. Look for a webhook pointing to `packagist.org`
150+
3. Check recent deliveries to ensure it's working
151+
152+
## Version Management
153+
154+
The version is managed through git tags. The `composer.json` file does not need a version field when publishing via Packagist, as versions are determined by your git tags.
155+
156+
However, if you want to include a version field in `composer.json` for local development, you can add:
157+
158+
```json
159+
{
160+
"version": "0.1.0"
161+
}
162+
```
163+
164+
Note: This version field is ignored by Packagist in favor of git tags.

0 commit comments

Comments
 (0)