Skip to content

Commit 178bd19

Browse files
floriankraemerfloriankraemer
committed
Documentation for analyzing external PHP projects
1 parent deaadf7 commit 178bd19

4 files changed

Lines changed: 250 additions & 0 deletions

File tree

‎README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -91,6 +91,7 @@ make docker-qa # Run QA in container
9191

9292
* [Installation](docs/Installation.md) - Install via Composer, PHAR, or Docker
9393
* [Usage](docs/Usage.md) - CLI usage, examples, output formats
94+
* [Running it with old PHP Versions](docs/Docker-External-Projects.md) - Run via Docker against legacy codebases / PHP versions
9495
* [Configuration](docs/Configuration.md) - YAML config options, regex patterns
9596
* [Detectors](docs/Detectors.md) - List of all detected BC breaks
9697
* [Custom Detectors](docs/Custom-Detectors.md) - Create your own detectors

‎docs/Docker-External-Projects.md‎

Lines changed: 246 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,246 @@
1+
# Running BC Check via Docker Against External Projects
2+
3+
This guide explains how to use BC Check via Docker to analyze external PHP projects when your host system runs an incompatible PHP version (e.g., PHP 7.x or 8.0-8.2).
4+
5+
## Why Use Docker for External Projects?
6+
7+
BC Check requires **PHP 8.3 or higher**, but many production systems or legacy projects still run older PHP versions. Docker allows you to:
8+
9+
- ✅ Run BC Check on any system with Docker installed
10+
- ✅ Analyze projects without modifying their PHP environment
11+
- ✅ Test backward compatibility across different PHP versions
12+
- ✅ Avoid version conflicts between host and project requirements
13+
14+
## Prerequisites
15+
16+
- **Docker** installed on your system
17+
- **Git** access to the target repository
18+
- **Basic command line knowledge**
19+
20+
## Quick Start
21+
22+
### 1. Clone BC Check Repository
23+
24+
```bash
25+
git clone https://github.com/Phauthentic/bc-check.git
26+
cd bc-check
27+
```
28+
29+
### 2. Build the Docker Image
30+
31+
```bash
32+
docker-compose build
33+
```
34+
35+
This creates a Docker image with PHP 8.3 and all necessary dependencies.
36+
37+
### 3. Run BC Check Against an External Project
38+
39+
```bash
40+
# Mount the external project as a volume
41+
docker-compose run --rm -v /path/to/external/project:/target:ro php bin/bc-check check /target v1.0.0 v2.0.0
42+
```
43+
44+
Replace:
45+
- `/path/to/external/project` with the actual path to your target project
46+
- `v1.0.0` and `v2.0.0` with the actual git references you want to compare
47+
48+
## Detailed Usage Examples
49+
50+
### Example 1: Local Project Directory
51+
52+
```bash
53+
# Analyze a project in your home directory
54+
docker-compose run --rm -v ~/projects/my-app:/target:ro php bin/bc-check check /target main develop
55+
```
56+
57+
### Example 2: Remote Repository Analysis
58+
59+
```bash
60+
# Clone and analyze a remote repository
61+
git clone https://github.com/example/project.git /tmp/project
62+
docker-compose run --rm -v /tmp/project:/target:ro php bin/bc-check check /target v1.0.0 v2.0.0
63+
```
64+
65+
### Example 3: CI/CD Pipeline Integration
66+
67+
```bash
68+
# In a CI environment, mount the workspace
69+
docker-compose run --rm -v $(pwd):/target:ro php bin/bc-check check /target $BASE_REF $HEAD_REF
70+
```
71+
72+
## Advanced Configuration
73+
74+
### Custom Configuration File
75+
76+
```bash
77+
# Mount a custom config file
78+
docker-compose run --rm \
79+
-v /path/to/project:/target:ro \
80+
-v /path/to/bc-check.yaml:/config/bc-check.yaml:ro \
81+
php bin/bc-check check /target v1.0.0 v2.0.0 --config=/config/bc-check.yaml
82+
```
83+
84+
### Different Output Formats
85+
86+
```bash
87+
# JSON output for programmatic processing
88+
docker-compose run --rm -v /path/to/project:/target:ro php bin/bc-check check /target v1.0.0 v2.0.0 --format=json
89+
90+
# GitHub Actions format
91+
docker-compose run --rm -v /path/to/project:/target:ro php bin/bc-check check /target v1.0.0 v2.0.0 --format=github-actions
92+
```
93+
94+
### Verbose File Processing
95+
96+
```bash
97+
# Show which files are being processed
98+
docker-compose run --rm -v /path/to/project:/target:ro php bin/bc-check check /target v1.0.0 v2.0.0 --show-files
99+
```
100+
101+
Output example:
102+
```
103+
Processing (source): src/Service/UserService.php
104+
Processing (source): src/Entity/User.php
105+
Processing (target): src/Service/UserService.php
106+
Processing (target): src/Entity/User.php
107+
108+
Found 2 BC break(s):
109+
✗ [METHOD_REMOVED] Public method App\Service\UserService::getUser() was removed
110+
✗ [METHOD_SIGNATURE_CHANGED] Method App\Service\UserService::createUser() has more required parameters (1 -> 2)
111+
112+
Time: 0.45s
113+
```
114+
115+
## Makefile Integration
116+
117+
For repeated analysis, create a Makefile in the BC Check directory:
118+
119+
```makefile
120+
.PHONY: analyze-external
121+
122+
# Analyze external project
123+
# Usage: make analyze-external PROJECT_PATH=/path/to/project FROM=v1.0.0 TO=v2.0.0
124+
analyze-external:
125+
ifndef PROJECT_PATH
126+
$(error PROJECT_PATH is required. Usage: make analyze-external PROJECT_PATH=/path/to/project FROM=v1.0.0 TO=v2.0.0)
127+
endif
128+
ifndef FROM
129+
$(error FROM is required. Usage: make analyze-external PROJECT_PATH=/path/to/project FROM=v1.0.0 TO=v2.0.0)
130+
endif
131+
ifndef TO
132+
$(error TO is required. Usage: make analyze-external PROJECT_PATH=/path/to/project FROM=v1.0.0 TO=v2.0.0)
133+
endif
134+
docker-compose run --rm -v $(PROJECT_PATH):/target:ro php bin/bc-check check /target $(FROM) $(TO) $(if $(CONFIG),--config=$(CONFIG),) $(if $(FORMAT),--format=$(FORMAT),) $(if $(filter true,$(VERBOSE)),--show-files,)
135+
```
136+
137+
Usage:
138+
```bash
139+
make analyze-external PROJECT_PATH=/home/user/my-project FROM=v1.0.0 TO=main
140+
make analyze-external PROJECT_PATH=/home/user/my-project FROM=v1.0.0 TO=main FORMAT=json
141+
make analyze-external PROJECT_PATH=/home/user/my-project FROM=v1.0.0 TO=main VERBOSE=true
142+
```
143+
144+
## Troubleshooting
145+
146+
### Permission Issues
147+
148+
If you encounter permission errors:
149+
150+
```bash
151+
# Ensure the target directory is readable
152+
chmod -R a+r /path/to/external/project
153+
```
154+
155+
### Git Repository Issues
156+
157+
If the target isn't a git repository or has issues:
158+
159+
```bash
160+
# Verify the target is a valid git repository
161+
cd /path/to/external/project
162+
git status
163+
git log --oneline -5
164+
```
165+
166+
### Docker Volume Mounting Issues
167+
168+
On some systems, you might need to use absolute paths:
169+
170+
```bash
171+
# Use absolute paths for volume mounting
172+
docker-compose run --rm -v $(realpath /path/to/project):/target:ro php bin/bc-check check /target v1.0.0 v2.0.0
173+
```
174+
175+
### Memory Issues
176+
177+
For large codebases, increase Docker memory:
178+
179+
```bash
180+
# In docker-compose.yml, add memory limits
181+
services:
182+
php:
183+
# ... existing config ...
184+
deploy:
185+
resources:
186+
limits:
187+
memory: 1G
188+
```
189+
190+
## Performance Considerations
191+
192+
- **Volume mounting**: Use `:ro` (read-only) for better performance and security
193+
- **Caching**: Docker layer caching speeds up subsequent runs
194+
- **Resource limits**: Monitor memory usage for large projects
195+
196+
## Integration Examples
197+
198+
### GitHub Actions
199+
200+
```yaml
201+
name: BC Check
202+
on: [pull_request]
203+
204+
jobs:
205+
bc-check:
206+
runs-on: ubuntu-latest
207+
steps:
208+
- uses: actions/checkout@v4
209+
with:
210+
path: target-project
211+
212+
- uses: actions/checkout@v4
213+
with:
214+
repository: 'Phauthentic/bc-check'
215+
path: bc-check
216+
217+
- name: Run BC Check
218+
working-directory: bc-check
219+
run: |
220+
docker-compose build
221+
docker-compose run --rm -v ../target-project:/target:ro php bin/bc-check check /target ${{ github.event.pull_request.base.sha }} ${{ github.event.pull_request.head.sha }}
222+
```
223+
224+
### Jenkins Pipeline
225+
226+
```groovy
227+
pipeline {
228+
agent any
229+
stages {
230+
stage('BC Check') {
231+
steps {
232+
sh '''
233+
git clone https://github.com/Phauthentic/bc-check.git bc-check
234+
cd bc-check
235+
docker-compose build
236+
docker-compose run --rm -v ../:/target:ro php bin/bc-check check /target main ${GIT_COMMIT}
237+
'''
238+
}
239+
}
240+
}
241+
}
242+
```
243+
244+
---
245+
246+
**Note**: This approach ensures BC Check runs in its required PHP 8.3+ environment while analyzing projects on systems with older PHP versions, enabling backward compatibility testing across different PHP ecosystems.

‎docs/Installation.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -69,6 +69,8 @@ Or use the Docker image directly:
6969
docker run --rm -v $(pwd):/app phauthentic/bc-check check /app abc123 def456
7070
```
7171

72+
For analyzing **external projects** (especially on systems with older PHP versions), see the [Docker External Projects](Docker-External-Projects.md) guide.
73+
7274
## Verify Installation
7375

7476
Verify the installation by running:

‎docs/Usage.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -155,6 +155,7 @@ make bc-check
155155

156156
## Next Steps
157157

158+
- [Docker External Projects](Docker-External-Projects.md) - Run via Docker against external codebases
158159
- [Configuration](Configuration.md) - Configure filtering and patterns
159160
- [Detectors](Detectors.md) - See all detected BC breaks
160161
- [CI Integration](CI-Integration.md) - Integrate with CI/CD pipelines

0 commit comments

Comments
 (0)