Skip to content

Commit 169e709

Browse files
claudeclaude
committed
docs: update README with automated workflow documentation
- Update architecture diagram to reflect auto-trigger workflow - Simplify release creation process (automatic after build) - Add quick start examples with correct dicoding-dev URLs - Document all workflow triggers and automation - Add troubleshooting section - Improve formatting and clarity - Add feature highlights and supported versions
1 parent b622768 commit 169e709

1 file changed

Lines changed: 189 additions & 58 deletions

File tree

‎README.md‎

Lines changed: 189 additions & 58 deletions
Original file line numberDiff line numberDiff line change
@@ -1,98 +1,229 @@
11
# PHP gRPC Releases
22

3-
Automated release management for pre-compiled PHP gRPC extensions.
3+
Automated release management for pre-compiled PHP gRPC extensions with **zero-touch publishing**.
44

5-
This repository downloads gRPC extensions built from [php-grpc-1.8RC](https://github.com/agissept/php-grpc-1.8RC) and publishes them to GitHub Releases for easy distribution.
5+
Build gRPC → Artifacts Generated → **Release Published Automatically** 🚀
66

7-
## Usage
7+
## Features
88

9-
### Option 1: Download Binary Files
10-
Download pre-compiled `.so` files from [Releases](https://github.com/agissept/php-grpc-releases/releases)
9+
✅ **Fully Automated** - No manual steps needed after triggering build
10+
✅ **Multi-Architecture** - AMD64 & ARM64 binaries
11+
✅ **Easy Integration** - Use in Dockerfile with simple curl
12+
✅ **Version Tracking** - gRPC and PHP version in release tags
13+
14+
---
15+
16+
## Quick Start
17+
18+
### Option 1: Download Pre-built Binaries
19+
20+
Visit [GitHub Releases](https://github.com/dicoding-dev/php-grpc-releases/releases) and download:
21+
- `grpc-amd64.so` - For x86_64 servers
22+
- `grpc-arm64.so` - For ARM64 servers
1123

1224
### Option 2: Use in Dockerfile
1325

1426
```dockerfile
15-
# Example for PHP 8.3 with gRPC v1.80.0
27+
# Example: PHP 8.3 with gRPC v1.80.0
1628
FROM php:8.3.29-fpm
1729

18-
# Download gRPC extension from GitHub Releases
30+
# Download & install pre-compiled gRPC
1931
RUN curl -L -o /tmp/grpc.so \
20-
https://github.com/agissept/php-grpc-releases/releases/download/v1.80.0-php8.3/grpc-amd64.so && \
32+
https://github.com/dicoding-dev/php-grpc-releases/releases/download/v1.80.0-php8.3/grpc-amd64.so && \
2133
mv /tmp/grpc.so /usr/local/lib/php/extensions/no-debug-non-zts-20220829/ && \
22-
docker-php-ext-enable grpc
34+
docker-php-ext-enable grpc && \
35+
rm -rf /tmp/*
2336
```
2437

38+
---
39+
2540
## How It Works
2641

27-
1. Build gRPC in [php-grpc-1.8RC](https://github.com/agissept/php-grpc-1.8RC) using GitHub Actions
28-
2. Trigger this repo's workflow with the build run ID
29-
3. Artifacts are automatically downloaded and published to GitHub Releases
30-
4. Use the release URL in your Dockerfile
42+
### Architecture
43+
44+
```
45+
┌─────────────────────────────────────────────────────┐
46+
│ Build Trigger │
47+
│ (gRPC Version + PHP Version) │
48+
└────────────────┬────────────────────────────────────┘
49+
│
50+
▼
51+
┌─────────────────────────────────────────────────────┐
52+
│ build-grpc.yml (GitHub Actions Workflow) │
53+
│ • Compile gRPC extensions │
54+
│ • Upload AMD64 & ARM64 artifacts │
55+
└────────────────┬────────────────────────────────────┘
56+
│
57+
▼ (Auto-Trigger)
58+
┌─────────────────────────────────────────────────────┐
59+
│ publish-to-releases.yml (GitHub Actions) │
60+
│ • Download artifacts │
61+
│ • Extract versions from artifact names │
62+
│ • Create GitHub Release │
63+
└────────────────┬────────────────────────────────────┘
64+
│
65+
▼
66+
┌─────────────────────────────────────────────────────┐
67+
│ 📦 GitHub Releases (Public Downloads) │
68+
│ Tag: v{GRPC_VERSION}-php{PHP_VERSION} │
69+
│ Example: v1.80.0-php8.3 │
70+
└─────────────────────────────────────────────────────┘
71+
```
72+
73+
### Workflow Triggers
74+
75+
| Workflow | Trigger | Action |
76+
|----------|---------|--------|
77+
| **build-grpc.yml** | Manual dispatch | Compile gRPC + upload artifacts |
78+
| **publish-to-releases.yml** | Auto (on build success) | Download artifacts → create release |
79+
| **publish-to-releases.yml** | Manual dispatch | Override auto-detection for custom releases |
80+
81+
---
3182

32-
## Workflow: Publish gRPC to GitHub Releases
83+
## Creating a New Release
3384

34-
**Trigger:** Manual (workflow_dispatch)
85+
### Automatic Process (Recommended)
3586

36-
**Inputs:**
37-
- `grpc_version` - gRPC version (e.g., 1.80.0RC1, 1.80.0)
38-
- `php_version` - PHP version (e.g., 8.3)
39-
- `source_run_id` - GitHub Actions Run ID (optional, auto-finds latest if empty)
87+
1. **Trigger Build Workflow:**
88+
```bash
89+
gh workflow run build-grpc.yml \
90+
--repo dicoding-dev/php-grpc-releases \
91+
--field grpc_version=1.80.0 \
92+
--field php_version=8.3
93+
```
4094

41-
**Steps:**
42-
1. Find build artifacts from php-grpc-1.8RC
43-
2. Download AMD64 and ARM64 binaries
44-
3. Create GitHub Release with assets
45-
4. Generate download URLs
95+
2. **Done! 🎉** The publish workflow will automatically:
96+
- Wait for build to complete
97+
- Download artifacts
98+
- Extract version info
99+
- Create GitHub Release
100+
- Generate download URLs
101+
102+
### Manual Process (Via GitHub UI)
103+
104+
1. Go to [Actions → Build gRPC PHP](https://github.com/dicoding-dev/php-grpc-releases/actions/workflows/build-grpc.yml)
105+
2. Click **"Run workflow"**
106+
3. Enter gRPC version and PHP version
107+
4. Click **"Run workflow"**
108+
5. Wait for build to complete...
109+
6. Release will be created automatically ✨
110+
111+
---
46112

47113
## Release Format
48114

49-
Releases use the following convention:
115+
### Release Naming Convention
116+
50117
```
51118
Tag: v{GRPC_VERSION}-php{PHP_VERSION}
52-
Example: v1.80.0-php8.3
119+
Example: v1.80.0RC1-php8.3
53120
```
54121

122+
### Available Binaries
123+
55124
Each release includes:
56-
- `grpc-amd64.so` - AMD64 architecture
57-
- `grpc-arm64.so` - ARM64 architecture
125+
- **grpc-amd64.so** - For x86_64 (Intel/AMD) architecture
126+
- **grpc-arm64.so** - For ARM64 (Apple Silicon, Raspberry Pi, etc.)
58127

59-
## Architecture
128+
### Download URLs
60129

61130
```
62-
php-grpc-1.8RC (Build gRPC)
63-
↓
64-
Artifacts (amd64, arm64)
65-
↓
66-
php-grpc-releases (Publish)
67-
↓
68-
GitHub Releases (Public Download)
69-
↓
70-
Your Dockerfile (Use in container)
131+
https://github.com/dicoding-dev/php-grpc-releases/releases/download/v{GRPC_VERSION}-php{PHP_VERSION}/grpc-amd64.so
132+
https://github.com/dicoding-dev/php-grpc-releases/releases/download/v{GRPC_VERSION}-php{PHP_VERSION}/grpc-arm64.so
71133
```
72134

135+
---
136+
73137
## Supported Versions
74138

75-
- PHP: 8.1, 8.2, 8.3
76-
- gRPC: 1.80.0+
77-
78-
## How to Create a Release
79-
80-
1. Go to [php-grpc-1.8RC](https://github.com/agissept/php-grpc-1.8RC/actions/workflows/build-grpc.yml)
81-
2. Click "Run workflow"
82-
3. Fill in:
83-
- gRPC Version: `1.80.0` (or desired version)
84-
- PHP Version: `8.3` (or desired version)
85-
4. Wait for build to complete
86-
5. Note the Run ID from the completed workflow
87-
6. Go to [this repo's Actions](https://github.com/agissept/php-grpc-releases/actions/workflows/publish-to-releases.yml)
88-
7. Click "Run workflow"
89-
8. Fill in:
90-
- gRPC Version: `1.80.0`
91-
- PHP Version: `8.3`
92-
- Source Run ID: (the ID from step 5, optional if auto-finds it)
93-
9. Wait for release to be created
94-
10. Download from [Releases](https://github.com/agissept/php-grpc-releases/releases)
139+
### PHP Versions
140+
- PHP 8.1
141+
- PHP 8.2
142+
- PHP 8.3
143+
144+
### gRPC Versions
145+
- 1.80.0+
146+
- Release Candidates (1.80.0RC1, etc.)
147+
148+
---
149+
150+
## Workflow Files
151+
152+
### build-grpc.yml
153+
- Compiles gRPC PHP extension from PECL
154+
- Builds for both AMD64 and ARM64 architectures
155+
- Strips debug symbols to reduce binary size
156+
- Uploads artifacts with naming pattern: `grpc-{arch}-ubuntu22.04-php{version}-v{grpc_version}`
157+
158+
### publish-to-releases.yml
159+
- **Triggers:**
160+
- ✅ Automatic when `build-grpc.yml` completes
161+
- ✅ Manual override available
162+
- **Steps:**
163+
1. Download artifacts from build workflow
164+
2. Parse version info from artifact names
165+
3. Organize binaries
166+
4. Create GitHub Release with notes & assets
167+
5. Print download summary
168+
169+
---
170+
171+
## Troubleshooting
172+
173+
### Release not created after build?
174+
175+
Check the workflow logs:
176+
1. Go to [Actions](https://github.com/dicoding-dev/php-grpc-releases/actions)
177+
2. Click on the failed `publish-to-releases` run
178+
3. Look for error messages in the logs
179+
180+
Common issues:
181+
- **"No successful build found"** → Wait for build to complete first
182+
- **"Could not parse artifact name"** → Artifact naming mismatch
183+
- **"Release already exists"** → That version was already released (skip)
184+
185+
### Artifact download fails in Docker?
186+
187+
Verify URL format:
188+
```bash
189+
# Test the URL
190+
curl -I https://github.com/dicoding-dev/php-grpc-releases/releases/download/v1.80.0-php8.3/grpc-amd64.so
191+
# Should return: 302 Found (redirect to CDN)
192+
```
193+
194+
---
195+
196+
## Environment Details
197+
198+
- **Build OS:** Ubuntu 22.04
199+
- **PHP Build Extensions:** Development headers, CLI, PEAR, XML
200+
- **Binary Optimization:** Debug symbols stripped for smaller file size
201+
- **Architectures:** AMD64 (x86_64), ARM64
202+
203+
---
95204

96205
## License
97206

98207
Same as [php-grpc-1.8RC](https://github.com/agissept/php-grpc-1.8RC)
208+
209+
---
210+
211+
## Related Projects
212+
213+
- **Build Source:** [php-grpc-1.8RC](https://github.com/agissept/php-grpc-1.8RC)
214+
- **Official gRPC:** [grpc/grpc](https://github.com/grpc/grpc)
215+
- **PHP PECL gRPC:** [pecl.php.net](https://pecl.php.net/package/grpc)
216+
217+
---
218+
219+
## Contributing
220+
221+
Found an issue? Have suggestions?
222+
223+
- Create an issue: [GitHub Issues](https://github.com/dicoding-dev/php-grpc-releases/issues)
224+
- Check the workflow logs for debugging
225+
226+
---
227+
228+
**Last Updated:** 2026-04-07
229+
**Repository:** [dicoding-dev/php-grpc-releases](https://github.com/dicoding-dev/php-grpc-releases)

0 commit comments

Comments
 (0)