Initial commit

2025-11-30 08:50:21 +08:00
commit ea211e1421
7 changed files with 461 additions and 0 deletions
--- a/.claude-plugin/plugin.json
+++ b/.claude-plugin/plugin.json
@@ -0,0 +1,12 @@
+{
+  "name": "frankenphp",
+  "description": "Interacts with the FrankenPHP App Server.",
+  "version": "0.0.0-2025.11.28",
+  "author": {
+    "name": "Tim Green",
+    "email": "rawveg@gmail.com"
+  },
+  "skills": [
+    "./skills/frankenphp"
+  ]
+}
--- a/README.md
+++ b/README.md
@@ -0,0 +1,3 @@
+# frankenphp
+
+Interacts with the FrankenPHP App Server.
--- a/plugin.lock.json
+++ b/plugin.lock.json
@@ -0,0 +1,56 @@
+{
+  "$schema": "internal://schemas/plugin.lock.v1.json",
+  "pluginId": "gh:rawveg/skillsforge-marketplace:frankenphp",
+  "normalized": {
+    "repo": null,
+    "ref": "refs/tags/v20251128.0",
+    "commit": "6645323cb8690377b9ada43a278ac1d57a774e0a",
+    "treeHash": "3b48f304a9effffdd4bef1dc9901cbc44c9f748fcc1cf22a4807c901650e890c",
+    "generatedAt": "2025-11-28T10:27:51.003459Z",
+    "toolVersion": "publish_plugins.py@0.2.0"
+  },
+  "origin": {
+    "remote": "git@github.com:zhongweili/42plugin-data.git",
+    "branch": "master",
+    "commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390",
+    "repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data"
+  },
+  "manifest": {
+    "name": "frankenphp",
+    "description": "Interacts with the FrankenPHP App Server."
+  },
+  "content": {
+    "files": [
+      {
+        "path": "README.md",
+        "sha256": "f2646a8392f23c91812bcd3efc04bf3278404076b188e9c45690a1e3b48f75f2"
+      },
+      {
+        "path": ".claude-plugin/plugin.json",
+        "sha256": "99602f15c3904e854b1330e5b1cb053e022cbf0182732d6512b8affbe116f27a"
+      },
+      {
+        "path": "skills/frankenphp/plugin.json",
+        "sha256": "344a45e37dec7746748e2195b8461812c881eacafd74b057043a1b610dee294b"
+      },
+      {
+        "path": "skills/frankenphp/SKILL.md",
+        "sha256": "591dcc23481ced5a369c1929b6d6cbc22470225f6dff35881c6d6abcf21c60ad"
+      },
+      {
+        "path": "skills/frankenphp/references/index.md",
+        "sha256": "82e439f88f4cbc5cc892165a4672f7a44f788d7739d1817a4b113b2406754160"
+      },
+      {
+        "path": "skills/frankenphp/references/other.md",
+        "sha256": "29a7025b2eabc518d5376db7de44b164767c7f136b158b307198b287c516a2b8"
+      }
+    ],
+    "dirSha256": "3b48f304a9effffdd4bef1dc9901cbc44c9f748fcc1cf22a4807c901650e890c"
+  },
+  "security": {
+    "scannedAt": null,
+    "scannerVersion": null,
+    "flags": []
+  }
+}
--- a/skills/frankenphp/SKILL.md
+++ b/skills/frankenphp/SKILL.md
@@ -0,0 +1,357 @@
+---
+name: frankenphp
+description: FrankenPHP Documentation - Modern PHP application server built on Caddy
+---
+
+# FrankenPHP Skill
+
+Comprehensive assistance with FrankenPHP development - a modern PHP application server built on top of the Caddy web server. FrankenPHP enables persistent PHP processes with worker mode, automatic HTTPS, HTTP/2, HTTP/3, and real-time capabilities via Mercure integration.
+
+## When to Use This Skill
+
+This skill should be triggered when:
+- Setting up or configuring FrankenPHP server
+- Implementing FrankenPHP worker mode for performance optimization
+- Integrating FrankenPHP with Laravel, Symfony, or other PHP frameworks
+- Deploying PHP applications with Docker using FrankenPHP
+- Converting traditional PHP apps to use persistent workers
+- Configuring automatic HTTPS, HTTP/2, or HTTP/3
+- Implementing real-time features with Mercure
+- Creating standalone, self-executable PHP applications
+- Optimizing PHP application performance with persistent processes
+- Troubleshooting FrankenPHP worker mode or configuration issues
+
+## Quick Reference
+
+### Installation & Basic Server
+
+**Install via curl (Linux/macOS):**
+```bash
+curl https://frankenphp.dev/install.sh | sh
+mv frankenphp /usr/local/bin/
+
+# Start server in current directory
+frankenphp php-server
+```
+
+**Install via Homebrew:**
+```bash
+brew install dunglas/frankenphp/frankenphp
+frankenphp php-server
+```
+
+**Quick Docker deployment:**
+```bash
+docker run -v $PWD:/app/public \
+    -p 80:80 -p 443:443 -p 443:443/udp \
+    dunglas/frankenphp
+```
+
+### Basic Worker Mode
+
+**Start worker with standalone binary:**
+```bash
+frankenphp php-server --worker /path/to/your/worker/script.php
+```
+
+**Docker with worker mode:**
+```bash
+docker run \
+    -e FRANKENPHP_CONFIG="worker /app/public/index.php" \
+    -v $PWD:/app \
+    -p 80:80 -p 443:443 -p 443:443/udp \
+    dunglas/frankenphp
+```
+
+**Worker with 42 processes:**
+```bash
+docker run \
+    -e FRANKENPHP_CONFIG="worker ./public/index.php 42" \
+    -v $PWD:/app \
+    -p 80:80 -p 443:443 -p 443:443/udp \
+    dunglas/frankenphp
+```
+
+### Custom Worker Script
+
+**Basic worker pattern:**
+```php
+<?php
+// public/index.php
+
+ignore_user_abort(true);
+
+require __DIR__.'/vendor/autoload.php';
+
+$myApp = new \App\Kernel();
+$myApp->boot();
+
+$handler = static function () use ($myApp) {
+    try {
+        echo $myApp->handle($_GET, $_POST, $_COOKIE, $_FILES, $_SERVER);
+    } catch (\Throwable $exception) {
+        (new \MyCustomExceptionHandler)->handleException($exception);
+    }
+};
+
+$maxRequests = (int)($_SERVER['MAX_REQUESTS'] ?? 0);
+for ($nbRequests = 0; !$maxRequests || $nbRequests < $maxRequests; ++$nbRequests) {
+    $keepRunning = \frankenphp_handle_request($handler);
+    $myApp->terminate();
+    gc_collect_cycles();
+    if (!$keepRunning) break;
+}
+
+$myApp->shutdown();
+```
+
+### Laravel Integration
+
+**Laravel Octane installation:**
+```bash
+composer require laravel/octane
+php artisan octane:install --server=frankenphp
+php artisan octane:frankenphp
+```
+
+**Laravel with Docker:**
+```bash
+docker run -p 80:80 -p 443:443 -p 443:443/udp \
+    -v $PWD:/app \
+    dunglas/frankenphp
+```
+
+**Laravel Caddyfile:**
+```
+{
+	frankenphp
+}
+
+localhost {
+	root public/
+	encode zstd br gzip
+	php_server {
+		try_files {path} index.php
+	}
+}
+```
+
+**Octane with file watching:**
+```bash
+php artisan octane:frankenphp --watch
+```
+
+### Symfony Integration
+
+**Symfony worker with runtime:**
+```bash
+composer require runtime/frankenphp-symfony
+
+docker run \
+    -e FRANKENPHP_CONFIG="worker ./public/index.php" \
+    -e APP_RUNTIME=Runtime\\FrankenPhpSymfony\\Runtime \
+    -v $PWD:/app \
+    -p 80:80 -p 443:443 -p 443:443/udp \
+    dunglas/frankenphp
+```
+
+### Worker Management
+
+**Watch files for changes (auto-reload):**
+```bash
+frankenphp php-server --worker /path/to/worker.php \
+    --watch="/path/to/your/app/**/*.php"
+```
+
+**Restart workers via API:**
+```bash
+curl -X POST http://localhost:2019/frankenphp/workers/restart
+```
+
+**Configure max consecutive failures (Caddyfile):**
+```
+frankenphp {
+    worker {
+        max_consecutive_failures 10
+    }
+}
+```
+
+### Superglobals in Worker Mode
+
+**Accessing worker-bound vs request-bound values:**
+```php
+<?php
+// Capture worker-level values before request loop
+$workerServer = $_SERVER;
+
+$handler = static function () use ($workerServer) {
+    var_dump($_SERVER);      // Current request superglobals
+    var_dump($workerServer); // Original worker values
+};
+```
+
+## Key Concepts
+
+### Worker Mode
+FrankenPHP's worker mode keeps your PHP application loaded in memory between requests, dramatically improving performance. Instead of bootstrapping your application for each request (traditional PHP), the application boots once and handles thousands of requests with the same process.
+
+**Benefits:**
+- Boot your application once, handle requests in milliseconds
+- Persistent database connections
+- Preloaded classes and configuration
+- Significantly reduced memory overhead
+
+**Key Pattern:** Use `frankenphp_handle_request($handler)` to process each request within a persistent loop, calling `gc_collect_cycles()` after each request to prevent memory leaks.
+
+### Caddy Integration
+FrankenPHP is built on top of Caddy, meaning you get:
+- **Automatic HTTPS** - Zero-config TLS certificates via Let's Encrypt
+- **HTTP/2 & HTTP/3** - Modern protocol support out of the box
+- **Powerful configuration** - Use Caddyfile for server configuration
+
+### Early Hints (103 Status)
+FrankenPHP supports HTTP 103 Early Hints, allowing browsers to start loading critical resources (CSS, JS, fonts) while the server is still generating the full response.
+
+### Mercure Real-Time
+Built-in support for Mercure protocol enables real-time push notifications from server to browser using Server-Sent Events (SSE). Perfect for live updates, notifications, and collaborative features.
+
+## Reference Files
+
+This skill includes comprehensive documentation in `references/`:
+
+- **other.md** - Core FrankenPHP documentation including installation, configuration, worker mode, framework integration, deployment, and production setup
+
+The reference file contains detailed information from the official FrankenPHP documentation at https://frankenphp.dev/docs/
+
+Use the reference file when you need:
+- Detailed installation instructions for different platforms
+- Advanced Caddyfile configuration examples
+- Framework-specific integration patterns (Laravel, Symfony, WordPress, etc.)
+- Production deployment strategies
+- Performance optimization techniques
+- Static binary compilation guides
+- Docker configuration options
+
+## Working with This Skill
+
+### For Beginners
+1. **Start with basic installation** - Use the curl install script or Docker for quickest setup
+2. **Run traditional PHP first** - Use `frankenphp php-server` without worker mode to verify setup
+3. **Test with simple scripts** - Create a basic `index.php` to understand the server behavior
+4. **Learn Caddyfile basics** - Understand how to configure domains and paths
+5. **Gradually adopt worker mode** - Once comfortable, convert to worker mode for performance
+
+### For Laravel Developers
+1. **Use Laravel Octane** - The official integration provides the smoothest experience
+2. **Start with Docker** - Use the official `dunglas/frankenphp` image
+3. **Configure Mercure** - Add real-time capabilities to your Laravel app
+4. **Optimize workers** - Tune worker count based on your traffic patterns
+5. **Use file watching** - Enable `--watch` during development for auto-reload
+
+### For Symfony Developers
+1. **Install Symfony runtime** - Use `runtime/frankenphp-symfony` package
+2. **Set APP_RUNTIME** - Configure environment variable for automatic integration
+3. **Use worker mode** - Leverage persistent processes for maximum performance
+4. **Deploy with Docker** - Use official containers for production
+
+### For Production Deployment
+1. **Review worker configuration** - Set appropriate worker count and max requests
+2. **Configure failure handling** - Set `max_consecutive_failures` threshold
+3. **Enable monitoring** - Use Caddy admin API for health checks and metrics
+4. **Set up log analytics** - Configure structured JSON logs
+5. **Plan restart strategy** - Use `MAX_REQUESTS` or manual API restarts to prevent memory leaks
+6. **Test with load** - Validate performance under realistic traffic patterns
+
+### For Docker Users
+1. **Use official images** - Start with `dunglas/frankenphp` or `dunglas/frankenphp:static-builder`
+2. **Mount your app** - Volume mount your code to `/app`
+3. **Configure via ENV** - Use `FRANKENPHP_CONFIG` for worker setup
+4. **Expose ports** - Map 80, 443 (TCP), and 443 (UDP) for HTTP/3
+5. **Use localhost** - Access via `https://localhost` (not 127.0.0.1)
+
+## Common Patterns
+
+### Performance Optimization
+- **Use worker mode** for all production applications
+- **Set MAX_REQUESTS** to restart workers periodically (prevents memory leaks)
+- **Call gc_collect_cycles()** after each request in custom workers
+- **Tune worker count** based on CPU cores and memory available
+- **Enable HTTP/2 push** for critical assets
+
+### Development Workflow
+- **Use --watch flag** for automatic reload during development
+- **Traditional mode** for debugging (easier to trace issues)
+- **Docker for consistency** across development and production environments
+- **Caddyfile per environment** (dev, staging, prod) with different configs
+
+### Error Handling
+- **Wrap handlers** in try-catch blocks within worker loop
+- **Log exceptions** but keep worker running
+- **Use max_consecutive_failures** to restart problematic workers
+- **Monitor worker health** via Caddy admin API
+
+## Resources
+
+### Official Documentation
+- **Main docs:** https://frankenphp.dev/docs/
+- **Worker mode guide:** https://frankenphp.dev/docs/worker/
+- **Laravel integration:** https://frankenphp.dev/docs/laravel/
+- **Symfony integration:** https://frankenphp.dev/docs/symfony/
+
+### Framework Integration
+- Laravel Octane: Official integration via `laravel/octane` package
+- Symfony Runtime: Use `runtime/frankenphp-symfony` package
+- WordPress, Drupal, Joomla, TYPO3: Supported frameworks
+- API Platform: First-class FrankenPHP support
+
+### Docker Images
+- **Production:** `dunglas/frankenphp`
+- **Static builder:** `dunglas/frankenphp:static-builder`
+- **Latest tag:** Always includes PHP 8.4+ and popular extensions
+
+## Notes
+
+- FrankenPHP includes PHP 8.4 and most popular extensions in static binaries
+- Can be embedded as a Go library via `net/http` for custom applications
+- Worker mode requires careful superglobals management (use closures to capture state)
+- HTTPS is automatic via Let's Encrypt (no certificate configuration needed)
+- HTTP/3 support requires UDP port 443 to be accessible
+- File watching uses system-specific file monitoring (efficient, no polling)
+
+## Troubleshooting
+
+### Worker Not Starting
+- Check worker script path is absolute or relative to document root
+- Verify worker script has no syntax errors (`php -l script.php`)
+- Check file permissions (script must be readable)
+- Review logs for initialization errors
+
+### Memory Leaks in Workers
+- Call `gc_collect_cycles()` after each request
+- Set `MAX_REQUESTS` to restart workers periodically
+- Avoid global state accumulation
+- Check for unclosed resources (files, connections)
+
+### Performance Issues
+- Increase worker count (`FRANKENPHP_CONFIG="worker ./index.php 42"`)
+- Check worker restart frequency (too frequent = performance loss)
+- Review database connection pooling
+- Monitor memory usage per worker
+- Verify no blocking operations in request handler
+
+### HTTPS Not Working
+- Ensure ports 80 and 443 are accessible
+- Check firewall rules
+- Verify domain DNS points to server
+- Use `localhost` (not 127.0.0.1) for local development
+- Accept self-signed certificate in browser for local testing
+
+## Updating
+
+To stay current with FrankenPHP:
+1. Follow the official GitHub repository for updates
+2. Review changelog for breaking changes
+3. Test updates in staging environment
+4. Update Docker images regularly (`docker pull dunglas/frankenphp:latest`)
+5. Check framework-specific integration docs for version compatibility
--- a/skills/frankenphp/plugin.json
+++ b/skills/frankenphp/plugin.json
@@ -0,0 +1,15 @@
+{
+  "name": "frankenphp",
+  "description": "Provides FrankenPHP integration for Claude Code.",
+  "version": "1.0.0",
+  "author": {
+    "name": "Tim Green",
+    "email": "rawveg@gmail.com"
+  },
+  "homepage": "https://github.com/rawveg/claude-skills-marketplace",
+  "repository": "https://github.com/rawveg/claude-skills-marketplace",
+  "license": "MIT",
+  "keywords": ["frankenphp", "frankenphp-integration", "php", "app server", "Claude Code"],
+  "category": "productivity",
+  "strict": false
+}
--- a/skills/frankenphp/references/index.md
+++ b/skills/frankenphp/references/index.md
@@ -0,0 +1,7 @@
+# Frankenphp Documentation Index
+
+## Categories
+
+### Other
+**File:** `other.md`
+**Pages:** 1
--- a/skills/frankenphp/references/other.md
+++ b/skills/frankenphp/references/other.md
@@ -0,0 +1,11 @@
+# Frankenphp - Other
+
+**Pages:** 1
+
+---
+
+## FrankenPHP: the modern PHP app server
+
+**URL:** https://frankenphp.dev/docs/
+
+---