Getting Started

Install the package via Composer (composer require <vendor>/<package>) and publish its configuration if the package provides a config file (e.g., php artisan vendor:publish).
The primary entry point is the Refresh command (likely php artisan frankenphp:refresh or similar). Run php artisan list to find the exact command name provided by the package.
First use case: after deploying new code, run the refresh command to gracefully reload FrankenPHP workers without downtime. This is the most common day‑to‑day operation.
Check the package’s README for required environment variables (e.g., FRANKENPHP_BINARY) and ensure the FrankenPHP binary is accessible.
If you’re using Laravel Octane alongside FrankenPHP, verify that this package is compatible and configured to work with your Octane setup.

Implementation Patterns

Deployment integration: Add the refresh command to your deployment script (Envoyer, Deployer, GitHub Actions, etc.) as the final step after php artisan migrate and cache clearing. This ensures workers pick up the new code.
Scheduled refreshes: For long‑running applications, you might schedule a periodic refresh (e.g., every few hours) using Laravel’s scheduler to mitigate memory leaks. Use $schedule->command('frankenphp:refresh')->hourly();.
Event hooks: If the package dispatches events (e.g., FrankenPHPRefreshed, FrankenPHPRefreshFailed), listen to them to trigger custom logic such as notifications or metrics.
Configuration overrides: Many packages allow setting the FrankenPHP binary path, worker count, or retry attempts via config. Publish the config and adjust for your environment (e.g., different paths in local vs. production).
Combining with Octane: If this package is used with Laravel Octane, use Octane’s octane:reload for standard Swoole/RoadRunner setups, and this package’s refresh command specifically for FrankenPHP. Avoid running both simultaneously.

Version read failures: v1.1.1 fixes a bug where an unreadable FrankenPHP version caused the refresh to fail silently. Now it logs the error and retries. Ensure your logging is configured to capture warnings so you can spot version‑detection issues early.
Retry behaviour: The retry may introduce a short delay. If you run the refresh command in a CI/CD pipeline, set an appropriate timeout (e.g., 30–60 seconds) to accommodate retries.
Binary path: The package likely reads the FrankenPHP version by executing the binary. Make sure the binary is in your PATH or explicitly set in the config. In containerised environments, confirm the binary is available inside the container.
Debugging: If refresh fails, check storage/logs/laravel.log for messages containing “could not read FrankenPHP version” or similar. Also verify that FrankenPHP is running and that the process user has permission to execute the binary.
Extension points: The package may allow customising the version‑reading logic or the retry strategy via bindings or config. Look for interfaces or classes like FrankenPHPVersionResolver if you need to override behaviour.
No breaking changes: This is a patch release; existing usage patterns remain valid. However, if you were previously working around the version‑read bug (e.g., by manually setting a version), you can now remove such workarounds.