This is an example project of how to use the rhaarhoff/workflow package. You can read more about how the package works over there. Here I will explain how we used the package to create a functioning project.
Simply clone the project
git clone https://github.com/Flame1994/workflow-example.git
Copy the .env.example
and make sure to enter a valid database, name and password.
cp .env.example .env
Run composer install and dump autoload
composer install && composer dump-autoload
Make sure to run the key generator
php artisan key:generate
Run migration and seeders
php artisan migrate --seed
Run the workflow generator
php artisan workflow:generate
You should now have a working project. You can use postman
to query the api endpoints. Simply import
the following link into your postman and setup your own environment:
https://www.getpostman.com/collections/f9b1cbcc3e4ab53f1f64
This project consists of Companies, each having multiple clients. For each of them there are CRUDL endpoints as seen in the routes/api.php
file.
Every endpoint links to a function within a Controller
. This is where it gets interesting. Instead of the normal way
Laravel is being used, by either doing logic within the Controller, a Service, or a Repository, this package helps us split the functionality into more readible
chunks of code by using Workflows
.
The workflows can be found in the app/Workflows
folder. Each workflow folder has a Code
, Definition
and Generated
folder.
The Definition
folder contains all the definition files that specify how the workflow should function. Read more on this on the packages github page.
The Generated
folder contains all the Base
classes of the workflows. These are auto generated when running the following command:
php artisan workflow:generate
When running the command above, a Workflows/Common/Workflow.php
file will be generated as well. This class is the parent class
of all Workflows. If you have a decent understanding of the workflows you can even edit this to your liking.
Note: There is no need to add the base classes and Workflow.php to the repository if you can setup some devops to auto run the command to generate them
The Code
folder contains all the workflow classes where the business logic is being written.
You can see that every companies
endpoint links to a function within the CompanyController
. From there, every function starts its own
Workflow. For example, the CompanyController@create
function starts the WorkflowCompanyCreate
workflow and passes all required parameters as
specified in its definition file.
Using this structure we can easily see how the business logic flow of each endpoint is being used. The Controller is only being used to take input and give output. The Workflows are being used to actually do the business logic. There are a lot of better ways to handle and parse the input & ouput. I just wanted to show a very basic version of what the workflows can do. I did not put much effort into the input, output and exception throwing.
Let's take a look at a workflow. Visit the Workflows/Company/Code/WorkflowCompanyCreate.php
class.
You will see that there is an execute
function. This is used when calling the workflow from another place in your project. You can see that
we call this function from the CompanyController@create
function, like this:
$company = WorkflowCompanyCreate::execute(
$request->get('name'),
$request->get('email'),
$request->get('founded')
);
Which passes all the required parameters in order to create the company.
You can also see that every function within this workflow is defined in the corresponding definition file Workflows/Company/Definition/CompanyCreate.json
. Make sure you understand how
the definition files work before using this, since they are the backbone of everything.
If you make changes to a definition file, make sure to run the generate command:
php artisan workflow:generate
since it will update the base classes. In turn, you will need to update the classes extending the base classes that were updated.
The Laravel Workflow generator is open-sourced software licensed under the MIT license.