b03511f99b
Update AGENT.md to reflect current project structure and philosophy Add comprehensive architecture documentation covering: - Directory layout - Stable contracts - Request flow - Module dependencies - Page vs list detection - Deployment models - Demo fallback Remove outdated plugin system documentation Add new content system documentation Add configuration documentation Add context API documentation Add hooks and plugins documentation Add templates documentation Add rendering documentation Add development environment documentation
130 lines
3.6 KiB
Markdown
130 lines
3.6 KiB
Markdown
# Development Environment
|
|
|
|
## Container Setup
|
|
|
|
Located in `devel/`. Uses Podman (Docker-compatible).
|
|
|
|
### Containerfile
|
|
|
|
Base image: `php:8.4.14-apache` with Xdebug for profiling.
|
|
|
|
```
|
|
FROM php:8.4.14-apache
|
|
# Xdebug installed with profile mode
|
|
# Trigger profiling: ?XDEBUG_PROFILE=1
|
|
# Output: /tmp/cachegrind.out.*
|
|
```
|
|
|
|
### compose.yaml
|
|
|
|
**Default service** (demo mode):
|
|
|
|
```yaml
|
|
default:
|
|
build: ./
|
|
container_name: folderweb-default
|
|
volumes:
|
|
- ../app:/var/www/app:z
|
|
- ./apache/custom.conf:/etc/apache2/conf-available/custom.conf:z
|
|
- ./apache/default.conf:/etc/apache2/sites-available/000-default.conf:z
|
|
ports:
|
|
- "8080:80"
|
|
```
|
|
|
|
Mounts `app/` only — uses `app/default/content/` as demo content.
|
|
|
|
**Custom service** (commented out, template for production-like setup):
|
|
|
|
```yaml
|
|
custom:
|
|
volumes:
|
|
- ../app:/var/www/app:z
|
|
- ../content:/var/www/html:z # Content as document root
|
|
- ../custom:/var/www/custom:z # Custom overrides
|
|
- ../docs:/var/www/html/docs:z # Docs served as content
|
|
ports:
|
|
- "4040:80"
|
|
```
|
|
|
|
### Starting
|
|
|
|
```bash
|
|
cd devel
|
|
podman-compose build
|
|
podman-compose up -d
|
|
# Demo: http://localhost:8080
|
|
```
|
|
|
|
## Apache Configuration
|
|
|
|
### default.conf (VirtualHost)
|
|
|
|
- `DocumentRoot /var/www/html`
|
|
- `DirectoryIndex disabled` (no auto-index)
|
|
- RewriteRule: all non-`/app/` requests → `/app/router.php`
|
|
|
|
### custom.conf (Aliases)
|
|
|
|
Maps `/app/*` URLs to filesystem:
|
|
|
|
```
|
|
Alias /app/default-styles /var/www/app/default/styles
|
|
Alias /app/styles /var/www/custom/styles
|
|
Alias /app/fonts /var/www/custom/fonts
|
|
Alias /app /var/www/app
|
|
```
|
|
|
|
More specific aliases listed first (Apache processes in order). Enables `mod_rewrite`.
|
|
|
|
### Production Deployment
|
|
|
|
The Apache config in `devel/` is a reference. Production may vary but must ensure:
|
|
|
|
1. **All requests** (except `/app/*`) rewrite to `/app/router.php`
|
|
2. **`/app/` aliased** to the `app/` directory
|
|
3. **`/app/styles/`** aliased to `custom/styles/`
|
|
4. **`/app/fonts/`** aliased to `custom/fonts/`
|
|
5. **Document root** set to the content directory
|
|
6. **`custom/`** accessible to PHP at `../custom/` relative to `app/`
|
|
7. **`DirectoryIndex disabled`** — the router handles all paths
|
|
|
|
Nginx equivalent: proxy all non-asset requests to `app/router.php`, alias `/app/` paths accordingly.
|
|
|
|
## Performance Testing
|
|
|
|
**`devel/perf.sh`** — All-in-one profiling tool using Xdebug + Podman.
|
|
|
|
### Commands
|
|
|
|
| Command | Purpose |
|
|
|---|---|
|
|
| `./perf.sh profile /url` | Profile a URL, show top 20 slowest functions |
|
|
| `./perf.sh analyze [file]` | Analyze a cachegrind file (latest if omitted) |
|
|
| `./perf.sh list` | List available cachegrind profiles |
|
|
| `./perf.sh clean` | Remove all cachegrind files |
|
|
| `./perf.sh generate <size>` | Generate test data: `small` (~100), `medium` (~500), `large` (~1500), `huge` (~5000+) |
|
|
| `./perf.sh generate custom N M D` | Custom: N categories, M posts/cat, D depth levels |
|
|
| `./perf.sh testdata-stats` | Show test data statistics |
|
|
| `./perf.sh testdata-clean` | Remove test data |
|
|
|
|
### Environment Variables
|
|
|
|
```bash
|
|
CONTAINER=folderweb-default # Target container name
|
|
PORT=8080 # Target port
|
|
```
|
|
|
|
### Profiling Workflow
|
|
|
|
```bash
|
|
cd devel
|
|
./perf.sh generate medium # Create test dataset
|
|
./perf.sh profile / # Profile homepage
|
|
./perf.sh profile /blog-321/ # Profile a specific page
|
|
|
|
# Export for KCachegrind
|
|
podman cp folderweb-default:/tmp/cachegrind.out.123 ./profile.out
|
|
kcachegrind ./profile.out
|
|
```
|
|
|
|
Focus on functions consuming >5% of total execution time. The analyzer shows time (ms), memory (KB), call count, and percentage.
|