README

WORK IN PROGRESS - Recomended for demo purposes only.

This package adds a new way of thinking about Models and Functional Workflows. I intend to have companion package Stromite Filament that will add easy UI configuration using the Filament package.

High Level Concepts

Package Terminology:

Entity
- Entity Type
- Settings
- Setting Groups (Associated Settings such as Address, City, Zip)
Workflow
- Action
- Node
- Edge
- Instance
- Trigger
- Version

Entities

Often times while developing new projects it can be hard to know what the final form of your Models will be. It may be easier to not have to deal with migrations and DB edits. Stromite aims to help prototype faster by alleviating this headache.

Enter the Entity/Setting structure. A set of Models that are preconfigured to allow a developer to create dynamic "Entity Types".

Pretend that an "Entity Type" is synonymous with a "Laravel Model" or "DB Table".

For example, we'll create a new EntityType called "Movie"

Now typically you'd create a migration and add the columns/properties you think you'll need. In Stromite terms we will call these "Settings". Any named datapoint you want to associate with your entity type.

For example, let's say that our "Movie" will need the following fields: "Title", "Release Year", "Genre". We will create "Settings" for these three fields and attach them to our "Entity Type"

Now we have an equivalent table for "Movies" with the settings we now have our equivalent to columns. But we don't actually have any Rows of data.

To add Movies, we must create an instance of an Entity of Type "Movie" and fill in the allowed settings. This can be repeated as many times as needed to build your complete dataset.

Workflows

Workflows are a little harder to explain without the UI editor the Filament Package will have. Regardless, they will work without an editor so I included it here.

In simplest terms a Workflow is a collection/ordering of functions you would like to call on a specific Entity Type.

The functions themselves are contained within a class called an "Action" these actions are stored in the DB so once you create the actual file you'll need to register it in the DB before a Workflow can use it.

Example: Stromite ships with an Action that can be used to set an entity setting within a workflow. See SetEntitySetting.

This provides a structure to setup something like Lego blocks of code that can be combined in any way within a workflow so that an end user can design their own business logic without needing to know how the black box works.

For instance, as a developer you can create an Action "SendEmail" that will send an email using the "EmailAddress" setting on whatever entity is passed in, with a parameter to set the email theme and any fillable details. Then an end user could create a workflow called "Send Welcome Email" and the add the Actions "SendEmail" then chain a "setEntitySetting" Action at the end to update a setting on the entity called "WelcomeEmailSent" = True. Then someone without any coding experience just effectively wrote a simple controller action.

If you have a library of these Actions then the possibilities for customizations are endless.

Installation

1. Install via Composer

composer require syntaxerrorllc/stromite

2. Run the migrations

Stromite ships its own migrations (all prefixed with stromite_) and the service provider loads them automatically, so a normal migration run is all you need:

php artisan migrate

3. Publish the config (optional)

The package config is merged in automatically. Publish a copy if you want to customize it:

php artisan vendor:publish --tag=config

This creates config/stromite.php.

4. Schedule the cron command

Workflows can be triggered by cron triggers — a time-based trigger type that stores a standard cron expression (e.g. */5 * * * *). These are evaluated by the stromite:workflow:cron command, which must be scheduled to run every minute (the same every-minute pattern Laravel's own scheduler uses). Without this, cron-triggered workflows will never fire.

use Illuminate\Support\Facades\Schedule;

Schedule::command('stromite:workflow:cron')->everyMinute();

...and make sure the Laravel scheduler itself is running. On a standard host that's a single system cron job:

* * * * * cd /path-to-your-project && php artisan schedule:run >> /dev/null 2>&1

Tip: run php artisan stromite:workflow:cron --dry-run to see which cron triggers are due without actually running them.

5. Queue worker (optional)

By default a workflow runs synchronously when it's triggered. If you enable queuing on a workflow (queue_enabled = true, with an optional queue_name / queue_delay), you'll need a worker running to process the ProcessWorkflow job:

php artisan queue:work

6. Companion Filament package (optional)

For a UI to configure entity types, settings, and workflows, install the companion Stromite Filament package. Stromite itself works fully without it — you can manage everything through the database, the Artisan commands below, or your own UI.

Usage

Running a workflow

Use the stromite:workflow:run command to execute a workflow against an entity (or a freshly created scratch entity) and inspect the resulting WorkflowLog:

# Run a workflow against an existing entity
php artisan stromite:workflow:run {workflow} --entity={entity-uuid}

# Create a temporary entity to run against
php artisan stromite:workflow:run {workflow} --create-entity

# Pass shared data and get JSON output
php artisan stromite:workflow:run {workflow} --create-entity --shared-data='{"key":"value"}' --json

Triggers and events

Workflows are kicked off by triggers, each mapped to a workflow event. The built-in events are:

Event	Class	How it's fired
`entity_setting_saved`	`EntitySettingSavedWorkflowEvent`	Automatically, when a matching setting is saved (via the `SettingSaving` event)
`cron`	`WorkflowCronEvent`	When `stromite:workflow:cron` runs and the trigger's cron expression is due

Custom events can be registered through the WorkflowEventsRegistry — see Extending Workflow Events.

Artisan commands

Command	Description
`stromite:workflow:run {workflow}`	Run a workflow against an entity and print its log. Options: `--entity`, `--create-entity`, `--shared-data`, `--json`
`stromite:workflow:cron`	Find and run all due cron triggers (schedule this every minute). Options: `--dry-run`
`stromite:generate:entity {type} {count}`	Generate a set of fake entities of a given entity type (default `500`)
`stromite:export:entity {type}`	Export an entity type (and its data) to JSON. Options: `--no-data`
`stromite:import:entity {filename}`	Import an entity type from a JSON file
`stromite:export:workflow {name?}`	Export a workflow (versions, nodes, edges, triggers) to JSON. Options: `--all`
`stromite:import:workflow {file?}`	Import a workflow from a JSON export. Options: `--force`

Testing

composer test

Changelog

Please see CHANGELOG for more information what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security

If you discover any security related issues, please email admin@syntaxerror-llc.com instead of using the issue tracker.

syntaxerrorllc / stromite

Maintainers

Package info

Statistics

Security

README

High Level Concepts

Entities

Workflows

Installation

1. Install via Composer

2. Run the migrations

3. Publish the config (optional)

4. Schedule the cron command

5. Queue worker (optional)

6. Companion Filament package (optional)

Usage

Running a workflow

Triggers and events

Artisan commands

Testing

Changelog

Contributing

Security

Credits

License

Laravel Package Boilerplate