Skip to content

Make Laravel-oriented PHP service mode role-safe and fully documented #37

Description

@rmcdaniel

Problem

On main at b6c427ed3e40b921921461cde3ac14e85f644831, the Laravel bridge defers application-credential resolution for LaravelWorkflowClientInterface, but the separately documented WorkflowClientInterface remains an alias of the eager concrete Client. A Laravel command, controller, listener, job, or service that constructor-injects that lower-level interface can therefore abort an unrelated worker-only Artisan process during container resolution when only a worker credential is present, even though no application-client operation is performed.

Acceptance criteria

  • Container resolution and constructor injection of both LaravelWorkflowClientInterface and WorkflowClientInterface are credential-lazy.
  • The first real application-client operation without a client credential fails clearly before transport.
  • WorkerFactory and durable-workflow:worker resolve only worker credentials and remain operational when application services inject either or both documented interfaces.
  • The concrete Client may remain an explicit eager low-level surface, but public Laravel guidance distinguishes it from the normal role-safe interface path.
  • Laravel fakes replace both interfaces coherently without constructing a network client.
  • Clean-application and config-cache compatibility regressions cover worker-only bootstrap with both interfaces, client-only operations, and the supported Laravel/PHP matrix.
  • A published successor passes the Laravel/Symfony by standalone Server/managed Cloud framework qualification and the application-shaped Sample App service-mode smoke.

Delete when

Delete when a publicly installable PHP SDK release proves worker-only Laravel startup with services injecting both documented interfaces, while the first unauthorized application-client operation still fails before transport.

Consolidated scope

Role-safe dependency injection and discoverable inbound Message Streams are part of the same Laravel-quality service-mode experience.

sdk-php/issues/39: Document inbound durable message streams for PHP service mode

Problem

The PHP SDK exposes inbound durable message streams through WorkflowHandle::appendMessage(), WorkflowContext::messageStream(), MessageStream::receive(), and receiveOne(), but the public README and developer-portal guides do not show this workflow. Generated API reference and changelog entries are not enough for a first-time user to discover the feature or distinguish it from outbound run-scoped Workflow Streams and ordinary one-shot signals.

Acceptance criteria

  • Add a task-oriented PHP service-mode example that appends messages with stable message IDs and consumes one message or a bounded ordered batch from workflow code.
  • Explain that inbound Message Streams are instance-scoped repeated input, while Workflow Streams are run-scoped output and signals remain one-shot input.
  • Describe duplicate identity outcomes, replay-safe cursor advancement, worker replacement, and continue-as-new behavior without exposing or recommending the runtime-reserved transport signal.
  • Make the guide discoverable from the existing messages/workflow navigation and from the README, with Cloud and self-hosted ownership described consistently.
  • Keep examples checked against the public PHP API without turning headings or prose layout into brittle requirements.

Delete when

Delete when a first-time PHP user can find the guide, append repeated input, consume it deterministically, and understand how the feature differs from Workflow Streams and signals using only public documented APIs.

Metadata

Metadata

Assignees

No one assigned

    Labels

    authority:githubGitHub is the authoritative lifecycle record for this workbeta:compatibleMay be completed without changing the frozen beta contractkind:defectA public product behavior is incorrectpriority:P2Normal-priority product workrepo:sdk-phpOwned by the PHP SDK repositorystatus:in-progressApproved work is actively being implemented or validated

    Type

    No type

    Projects

    No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions