Skip to content

Fix tail log methods returning untyped array responses#37

Open
guillaumedelre wants to merge 1 commit intosupervisorphp:mainfrom
guillaumedelre:feature/issue-34
Open

Fix tail log methods returning untyped array responses#37
guillaumedelre wants to merge 1 commit intosupervisorphp:mainfrom
guillaumedelre:feature/issue-34

Conversation

@guillaumedelre
Copy link
Copy Markdown

@guillaumedelre guillaumedelre commented May 8, 2026

Closes #1, closes #34.

## Core fix: tail log methods

tailProcessStdoutLog() and tailProcessStderrLog() were routed through
__call() and returned a raw array [bytes, offset, overflow] with no
indication of what each index contained. This made the methods unusable
without reading the Supervisor API documentation directly.

- Introduce TailLogInterface and TailLog value object following the
  existing ReloadResult pattern
- Add explicit tailProcessStdoutLog() / tailProcessStderrLog() methods
  on Supervisor and SupervisorInterface, returning TailLogInterface
- Add TailLogSpec (5 examples) and SupervisorSpec coverage for both methods
- Document the offset-based iteration pattern in README and clarify that
  FailedException (fault 30) is thrown when the process log file does
  not exist yet
- Remove outdated notice about the PHP XML-RPC extension

## Typed DTO for getState()

getState() previously returned a raw array via __call(). Introduce
StateInfo and StateInfoInterface (statecode + statename), following the
same pattern as TailLog. Update getServiceState() to delegate to
getState()->getStateCode().

## Bug fixes

- Process::checkState() and Supervisor::checkState(): return false
  explicitly when ServiceStates/ProcessStates::tryFrom() yields null for
  an unknown int, instead of comparing an enum to null silently
- Remove unused ReloadExceptions import from Supervisor and
  SupervisorInterface (class does not exist)
- isConnected(): log the exception message at debug level instead of
  discarding it silently
- Process::offsetGet(): throw OutOfBoundsException on unknown key
  instead of returning null silently

## Code quality

- Normalise @method docblocks: integer/boolean -> int/bool
- Fix duplicate docblock on ProcessInterface::getState()
- Remove unused ReturnTypeWillChange import from Process
- Set minimum-stability to stable in composer.json
- Annotate array parameters with generic types for PHPStan level 8
  compatibility (array<int, mixed>, array<string, mixed>, list<string>,
  array shapes, class-string<SupervisorException>)
- Extend CI matrix to PHP 8.1, 8.2, 8.3 and 8.4

## Tests

- Add ReloadResultSpec: fromReloadConfig() parsing, null-safe fallback,
  getAffected() merge (7 examples)
- Add 5 specs for reloadAndApplyConfig(): removed groups, modified
  groups with and without stopModifiedGroups flag, added groups with and
  without startNewProcesses flag
- Add StateInfoSpec (5 examples)

Closes supervisorphp#1, closes supervisorphp#34.

## Core fix: tail log methods

tailProcessStdoutLog() and tailProcessStderrLog() were routed through
__call() and returned a raw array [bytes, offset, overflow] with no
indication of what each index contained. This made the methods unusable
without reading the Supervisor API documentation directly.

- Introduce TailLogInterface and TailLog value object following the
  existing ReloadResult pattern
- Add explicit tailProcessStdoutLog() / tailProcessStderrLog() methods
  on Supervisor and SupervisorInterface, returning TailLogInterface
- Add TailLogSpec (5 examples) and SupervisorSpec coverage for both methods
- Document the offset-based iteration pattern in README and clarify that
  FailedException (fault 30) is thrown when the process log file does
  not exist yet
- Remove outdated notice about the PHP XML-RPC extension

## Typed DTO for getState()

getState() previously returned a raw array via __call(). Introduce
StateInfo and StateInfoInterface (statecode + statename), following the
same pattern as TailLog. Update getServiceState() to delegate to
getState()->getStateCode().

## Bug fixes

- Process::checkState() and Supervisor::checkState(): return false
  explicitly when ServiceStates/ProcessStates::tryFrom() yields null for
  an unknown int, instead of comparing an enum to null silently
- Remove unused ReloadExceptions import from Supervisor and
  SupervisorInterface (class does not exist)
- isConnected(): log the exception message at debug level instead of
  discarding it silently
- Process::offsetGet(): throw OutOfBoundsException on unknown key
  instead of returning null silently

## Code quality

- Normalise @method docblocks: integer/boolean -> int/bool
- Fix duplicate docblock on ProcessInterface::getState()
- Remove unused ReturnTypeWillChange import from Process
- Set minimum-stability to stable in composer.json
- Annotate array parameters with generic types for PHPStan level 8
  compatibility (array<int, mixed>, array<string, mixed>, list<string>,
  array shapes, class-string<SupervisorException>)
- Extend CI matrix to PHP 8.1, 8.2, 8.3 and 8.4

## Tests

- Add ReloadResultSpec: fromReloadConfig() parsing, null-safe fallback,
  getAffected() merge (7 examples)
- Add 5 specs for reloadAndApplyConfig(): removed groups, modified
  groups with and without stopModifiedGroups flag, added groups with and
  without startNewProcesses flag
- Add StateInfoSpec (5 examples)

Signed-off-by: Guillaume Delré <delre.guillaume@gmail.com>
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.

Can't connect processes [FROM TODO] The current implementation does not work with log tailing

1 participant