Skip to content

feat: FrankenPHP worker-mode compatibility for BackgroundProcess#39

Open
HecFranco wants to merge 1 commit into
cocur:masterfrom
nowo-tech:feature/frankenphp-worker-compatibility
Open

feat: FrankenPHP worker-mode compatibility for BackgroundProcess#39
HecFranco wants to merge 1 commit into
cocur:masterfrom
nowo-tech:feature/frankenphp-worker-compatibility

Conversation

@HecFranco

Copy link
Copy Markdown

Makes cocur/background-process safe to use under FrankenPHP worker mode (and other long-lived PHP runtimes) by ensuring request-scoped process state does not leak across requests.

Changes

  • Implement Symfony\Contracts\Service\ResetInterface and reset() to clear $command / $pid between requests when the instance is a shared service
  • Document the recommended DI pattern: register Factory as a shared service and create a fresh BackgroundProcess per operation
  • Detect running processes via /proc/<pid> on Linux so isRunning() works in minimal Docker/FrankenPHP images without a ps binary
  • Fail fast with a clear RuntimeException when shell_exec is disabled
  • Raise the PHP requirement to >= 8.1, add symfony/service-contracts, and modernize the test suite for PHPUnit 10/11

Guidance for consumers

  • Do not block a worker thread with while ($process->isRunning()) { sleep(1); } inside an HTTP request
  • Persist the PID if the OS process must be managed after the request ends; use BackgroundProcess::createFromPID() later
  • Full details: docs/FRANKENPHP.md

Test plan

  • docker run --rm -v "$PWD":/app -w /app php:8.3-cli ./vendor/bin/phpunit -c ./
  • Review docs/FRANKENPHP.md for shared vs prototype service guidance
  • Confirm shell_exec is enabled in target FrankenPHP images (or use Messenger / a queue instead)

@HecFranco

Copy link
Copy Markdown
Author

Hi maintainers,

Thank you for maintaining this library and for keeping it available to the community over the years.

This merge request adds FrankenPHP worker-mode compatibility (ResetInterface / reset(), safer DI guidance, /proc-based process detection on Linux, and a clear guard when shell_exec is disabled) so the package remains reliable in long-lived PHP runtimes.

I would appreciate your review and approval when you have a moment.

Thank you again for your work and support.

Implement ResetInterface, document safe DI usage, detect processes via /proc on Linux, and guard disabled shell_exec so long-lived workers do not leak request state.
@HecFranco
HecFranco force-pushed the feature/frankenphp-worker-compatibility branch from ead9c00 to b6be940 Compare July 18, 2026 08:55
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant