Skip to content

Commit 5a58929

Browse files
c15k0c15k0
committed
docs: add operations and propel workflow guides with validation gate
1 parent f0e3e3e commit 5a58929

4 files changed

Lines changed: 433 additions & 57 deletions

File tree

‎README.md‎

Lines changed: 43 additions & 57 deletions
Original file line numberDiff line numberDiff line change
@@ -6,95 +6,81 @@
66

77
PSFS is a lightweight PHP framework for MVC/API applications (Twig + Propel + Symfony components).
88

9-
## Runtime baseline
9+
## 5-minute setup
1010

11-
- Execution and validation use Docker Compose.
12-
- Target PHP runtime: **8.3**.
13-
- Main services: `php`, `redis`, `db`.
14-
- Host port is configured via `.env` (`HOST_PORT=8008` by default).
11+
Prerequisites:
1512

16-
## Quick start
13+
- Docker + Docker Compose
14+
- Git
1715

16+
<!-- validated -->
1817
```bash
1918
docker compose up -d
2019
docker compose ps
21-
```
22-
23-
Run project commands inside the PHP container:
24-
25-
```bash
2620
docker exec core-php-1 php -v
27-
docker exec core-php-1 composer install
28-
docker exec core-php-1 php vendor/bin/phpunit --no-coverage
21+
docker exec core-php-1 composer install --no-interaction --prefer-dist
2922
```
3023

31-
If your PHP container name differs:
24+
If your PHP container name is not `core-php-1`:
3225

26+
<!-- validated -->
3327
```bash
3428
docker compose ps
3529
docker ps --format '{{.Names}}'
3630
```
3731

38-
## Swoole runtime
39-
40-
Check and run Swoole commands through `src/bin/psfs`:
32+
## Daily command map
4133

34+
<!-- example-only -->
4235
```bash
43-
docker exec core-php-1 php /var/www/src/bin/psfs psfs:swoole:check
44-
docker exec core-php-1 php /var/www/src/bin/psfs psfs:swoole:start --host=0.0.0.0 --port=8080
45-
docker exec core-php-1 php /var/www/src/bin/psfs psfs:swoole:status
46-
docker exec core-php-1 php /var/www/src/bin/psfs psfs:swoole:reload
47-
docker exec core-php-1 php /var/www/src/bin/psfs psfs:swoole:stop
48-
```
36+
# Run key tests
37+
docker exec core-php-1 php vendor/bin/phpunit --no-coverage --filter '/(AuthApiTest|RequestResponseSecurityContractTest)/'
4938

50-
Optional compose profile:
39+
# List PSFS CLI commands
40+
docker exec core-php-1 php src/bin/psfs list
5141

52-
```bash
53-
docker compose --profile swoole up -d php-swoole
54-
docker compose --profile swoole ps
42+
# Security local pre-check (act)
43+
act push --container-architecture linux/amd64
5544
```
5645

57-
## Security baseline (v2)
46+
## Choose your path
5847

59-
- Auth/cookies are versioned as `v2`.
60-
- Legacy fallback remains read-only until explicit removal approval.
61-
- Invalid auth must result in `null/null` and stop request flow.
62-
- Cookie policy target:
63-
- `HttpOnly=true`
64-
- `Secure=true` on HTTPS
65-
- `SameSite=Lax|Strict`
66-
- `Path=/`
67-
- coherent `Domain`
68-
- TTL aligned with session/auth policy
48+
### Onboarding path
6949

70-
## CI/CD security gates
50+
1. Read [Operations Playbook](./doc/OPERATIONS.md)
51+
2. Execute the "First day" flow
52+
3. Use troubleshooting matrix when blocked
7153

72-
Security pipeline blocks merge/release when:
54+
### Core contributor path
7355

74-
- a `must_pass` security control test fails,
75-
- any high/critical finding is unresolved,
76-
- hardening or quality gate returns non-pass.
56+
1. Read [Core Contracts](./doc/CONTRACTS.md)
57+
2. Read [Async Jobs and Connectors Contracts](./doc/contracts/async-jobs-connectors-contracts.md)
58+
3. Read [Security Plan and Artifacts](./doc/security/PLAN.md)
7759

78-
Local pre-check:
60+
## Propel models and migrations
7961

80-
```bash
81-
act push --container-architecture linux/amd64
82-
```
62+
For operational Propel flow (schema, model generation context, migration execution, rollback, failure modes), see:
63+
64+
- [Propel Workflow](./doc/PROPEL_WORKFLOW.md)
65+
66+
## Documentation quality gate
8367

84-
## Install as dependency
68+
Use the docs checker before opening PRs that touch docs:
8569

70+
<!-- validated -->
8671
```bash
87-
composer require psfs/core
88-
./vendor/bin/psfs psfs:create:root
72+
bash scripts/docs/validate_docs.sh
8973
```
9074

91-
## Documentation
75+
## Documentation index
9276

93-
- [Contracts](./doc/CONTRACTS.md)
94-
- [Versioning policy](./doc/VERSIONING.md)
95-
- [Async jobs and connectors contracts](./doc/contracts/async-jobs-connectors-contracts.md)
77+
- [Operations Playbook](./doc/OPERATIONS.md)
78+
- [Propel Workflow](./doc/PROPEL_WORKFLOW.md)
79+
- [Core Contracts](./doc/CONTRACTS.md)
80+
- [Versioning](./doc/VERSIONING.md)
81+
- [Async Jobs and Connectors Contracts](./doc/contracts/async-jobs-connectors-contracts.md)
9682

97-
## Notes
83+
## Rules
9884

99-
- Do not run `php`, `composer`, or `phpunit` directly on host for project validation.
100-
- Human review is required before committing automated/agent-driven changes.
85+
- Run project commands inside Docker containers.
86+
- Keep command blocks explicitly tagged as `validated` or `example-only`.

‎doc/OPERATIONS.md‎

Lines changed: 136 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,136 @@
1+
# PSFS Operations Playbook
2+
3+
Status: active
4+
Runtime baseline: Docker Compose + PHP 8.3
5+
6+
## 1) First day flow
7+
8+
### 1.1 Boot and verify runtime
9+
10+
<!-- validated -->
11+
```bash
12+
docker compose up -d
13+
docker compose ps
14+
docker exec core-php-1 php -v
15+
docker exec core-php-1 php src/bin/psfs list
16+
```
17+
18+
Expected markers:
19+
20+
- `core-php-1` is `Up`
21+
- `php src/bin/psfs list` prints PSFS commands (`psfs:migrate`, `psfs:queue:*`, `psfs:swoole:*`)
22+
23+
### 1.2 Verify security-critical tests
24+
25+
<!-- validated -->
26+
```bash
27+
docker exec core-php-1 php vendor/bin/phpunit --no-coverage --filter '/(AuthApiTest|RequestResponseSecurityContractTest)/'
28+
```
29+
30+
Expected marker: `OK` with tests executed.
31+
32+
## 2) Daily development loop
33+
34+
### 2.1 Start / stop / reset
35+
36+
<!-- validated -->
37+
```bash
38+
# Start
39+
docker compose up -d
40+
41+
# Stop
42+
docker compose stop
43+
44+
# Full teardown (containers + networks)
45+
docker compose down
46+
```
47+
48+
### 2.2 Install/update dependencies
49+
50+
<!-- validated -->
51+
```bash
52+
docker exec core-php-1 composer install --no-interaction --prefer-dist
53+
docker exec core-php-1 composer audit --no-interaction
54+
```
55+
56+
### 2.3 Run security gates locally
57+
58+
<!-- validated -->
59+
```bash
60+
docker exec core-php-1 php scripts/security/hardening_gate.php
61+
docker exec core-php-1 php scripts/security/quality_gate.php
62+
```
63+
64+
<!-- example-only -->
65+
```bash
66+
# CI workflow emulation
67+
act push --container-architecture linux/amd64
68+
```
69+
70+
## 3) Common workflows
71+
72+
### 3.1 Queue runtime
73+
74+
Important: queue jobs must be implemented and discoverable by `JobRegistry` before dispatching.
75+
76+
<!-- example-only -->
77+
```bash
78+
docker exec core-php-1 php src/bin/psfs psfs:queue:dispatch --code=<job_code> --payload='{"k":"v"}'
79+
docker exec core-php-1 php src/bin/psfs psfs:queue:work --queue=<queue_name> --max-jobs=10 --stop-when-empty=1
80+
docker exec core-php-1 php src/bin/psfs psfs:queue:run-parallel --queue=<queue_name> --workers=2 --stop-when-empty=1
81+
```
82+
83+
### 3.2 Swoole runtime
84+
85+
<!-- validated -->
86+
```bash
87+
docker exec core-php-1 php src/bin/psfs psfs:swoole:check
88+
```
89+
90+
<!-- example-only -->
91+
```bash
92+
docker exec core-php-1 php src/bin/psfs psfs:swoole:start --host=0.0.0.0 --port=8080
93+
docker exec core-php-1 php src/bin/psfs psfs:swoole:status
94+
docker exec core-php-1 php src/bin/psfs psfs:swoole:reload
95+
docker exec core-php-1 php src/bin/psfs psfs:swoole:stop
96+
```
97+
98+
## 4) Optimization knobs (safe defaults)
99+
100+
### 4.1 Runtime and PHP container
101+
102+
- Keep Docker as execution baseline for consistency with project contracts.
103+
- Use `--no-coverage` for local quick feedback.
104+
- Prefer filtered tests during iterative work; run broader suites before merge.
105+
106+
### 4.2 Queue backend strategy
107+
108+
- Priority path is Redis when available.
109+
- File queue is the persistent fallback.
110+
- Sync queue remains test-focused and in-process only.
111+
112+
### 4.3 Cache and deployment path
113+
114+
<!-- example-only -->
115+
```bash
116+
docker exec core-php-1 php src/bin/psfs psfs:deploy:project
117+
```
118+
119+
Use deploy command when you need to regenerate document root + route hydration in one path.
120+
121+
## 5) Troubleshooting matrix
122+
123+
| Symptom | Likely cause | Fix command |
124+
|---|---|---|
125+
| `Queue job "..." is not registered` | No queue job class implementing `QueueJobInterface::code()` discovered by registry | Implement/register job, then rerun dispatch (`psfs:queue:dispatch`) |
126+
| `Module without DB configuration, skipping process` on migrate | Target module lacks `Config/` DB setup | Ensure module config exists, then rerun `psfs:migrate` |
127+
| `psfs:swoole:check` reports missing runtime requirement | Missing extension/config in image | Rebuild/use image variant with required runtime extension |
128+
| Security gate status `block` | must-pass test failed or blocking finding exists | Run failing test filter + inspect `security/contracts/findings.json` |
129+
| PHPUnit exits with xdebug coverage warning | Coverage mode expected by config | Run with `--no-coverage` for local fast run |
130+
131+
## 6) Related references
132+
133+
- [Core Contracts](./CONTRACTS.md)
134+
- [Propel Workflow](./PROPEL_WORKFLOW.md)
135+
- [Async Jobs and Connectors Contracts](./contracts/async-jobs-connectors-contracts.md)
136+
- [Security Plan](./security/PLAN.md)

0 commit comments

Comments
 (0)