Download the PHP package chevere/workflow without Composer

Workflow

Summary

A Workflow is a configurable stored procedure that will run one or more jobs. Jobs are independent from each other, but interconnected as you can pass response references between jobs. Jobs supports conditional running based on variables and previous job responses.

Installing

Workflow is available through Packagist and the repository source is at chevere/workflow.

What it does?

The Workflow package provides a robust system for defining and executing structured procedures based on the workflow pattern. It enables to organize complex logic into a series of interconnected, independent jobs that can be executed in a controlled manner.

By breaking down monolithic procedures into modular workflow jobs, developers gain several advantages:

• Improved testability of individual components
• Better code organization and maintainability
• Reusable job definitions across different workflows
• Clear visualization of process flows
• Flexible execution patterns (sync/async)

::: tip 💡 Workflow introduction Read Workflow for PHP at Rodolfo's blog for a compressive introduction to this package. :::

How to use

The Workflow package provides a set of core functions in the Chevere\Workflow namespace that allow you to build and manage workflow processes. These functions work together to create flexible, maintainable workflow definitions.

Functions

Key concepts

• Action
• Variable: Shared workflow-level inputs accessed by multiple jobs
• Response: Links between job outputs (response()) and inputs

Workflow example

php demo/chevere.php

Create MyAction action by extending Chevere\Action\Action. You can also use ActionTrait.

Create Workflow with your MyAction Job:

Run the Workflow:

Variable

Use function variable to declare a Workflow variable that will be injected when running the workflow. Variables allow you to pass external values into your workflow jobs during execution.

When running the workflow, you must provide values for all declared variables:

Response

Use function response to declare a reference to a response returned by a previous Job. This allows you to chain job outputs as inputs to subsequent jobs.

🪄 When using a response it will auto declare the referenced Job as a dependency, ensuring proper execution order.

References can be also made on a response member identified by key.

Job

The Job class defines an Action that can be executed as part of a workflow.

Arguments

Job arguments can be passed in three ways:

• As-is values: Direct values passed to the Action
• Variables: Workflow-level inputs declared using the variable function
• Responses: References to previous job outputs declared using the response function

In the example above:

• The context argument is passed as-is with the value public.
• The userId argument is dynamically provided as a variable.
• The group argument is dynamically provided as a response from a previous job.
• The mask argument is passed as-is with the value 1024.

When running the Workflow, these arguments will be matched against the parameters defined in the main method of SomeAction.

Asynchronous

Use function async to create an asynchronous job, which runs non-blocking.

Important: When using async jobs, your Actions must support serialization. For Actions that work with non-serializable resources like:

• Database connections
• File handles
• Stream resources
• Network sockets

You must use sync jobs instead.

In the example below a Workflow describes an image creation procedure for multiple image sizes.

• variable('image') declares a Variable.
• response('thumb', 'filename') and response('medium', 'filename') declares a Response reference.

The graph for this Workflow says that thumb, medium and poster run non-blocking in parallel. Job store runs blocking (another node).

To complete the example, here's how to Run the Workflow previously defined:

Synchronous

Use function sync to create a synchronous job, which block execution until it gets resolved.

In the example below a Workflow describes an image uploading procedure.

• variable('payload') and variable('file') declares a Variable.
• response('meta', 'name') and response('user') declares a Response reference.

The graph for this Workflow says that all jobs run one after each other as all jobs are defined using sync.

To complete the example, here's how to Run the Workflow previously defined:

Conditional running

Method withRunIf enables to pass arguments of type Response for conditionally running a Job.

For the code above, all conditions must meet to run the Job and both variable compressImage and the reference SomeAction:doImageCompress must be true to run the job.

Dependencies

Use withDepends method to explicit declare previous jobs as dependencies. The dependent Job won't run until the dependencies are resolved.

Running

To run a Workflow use the run function by passing a Workflow and its variables (if any).

Access Job response

Use response to retrieve a job response as a CastArgument object which can be used to get a typed response.

🪄 If the response is of type array|ArrayAccess you can shortcut key access casting.

WorkflowTrait

The WorkflowTrait provides methods execute and run for easing handling a Workflow within a class.

Exception handling

When running a Workflow, if a Job fails a WorkflowException will be thrown. This is an exception wrapper for the job that thrown the exception.

Demo

See the demo directory for a set of examples.

Testing

Workflow provides several approaches for testing your implementations. While the Workflow itself doesn't need testing (it's a configuration), you should test:

1. Job actions (unit tests)
2. Workflow execution order (graph)
3. Job responses
4. Exception handling

Testing Job Actions

The primary testing focus should be on your Action implementations:

Testing Workflow Graph

Verify the execution order by testing the Workflow graph:

Testing Job Responses

Test how jobs interact by checking their responses:

Testing Exception Handling

Use ExpectWorkflowExceptionTrait to test error scenarios:

Architecture

The architecture of the Workflow package is designed to provide a clear separation of concerns, making it easier to define, manage, and execute workflows. The following diagram illustrates the core components and their interactions:

Documentation

Documentation is available at chevere.org/packages/workflow.

License

Copyright Rodolfo Berrios A.

This software is licensed under the Apache License, Version 2.0. See LICENSE for the full license text.

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.