PHP Masonry
[]
(https://php.net/)
[
]
(https://raw.githubusercontent.com/TheFoundryVisionmongers/Masonry/master/LICENSE.txt)
[
]
(https://packagist.org/packages/foundry/masonry)
[
]
(https://travis-ci.org/TheFoundryVisionmongers/Masonry/branches)
PHP Masonry is a way of building up a service using blocks of functionality. Tasks are retrieved from a pool, and are processed by workers. You can have any number of Workers, and any number of Tasks.
Installation
Install Masonry with Composer
composer require foundry/masonry -n
Contents
Architecture
โญโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฎ
โ (i) Mediator โ
โญโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฎ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโค
โ (i) Worker โโโโโโโโโค <Mediator> addWorker(<Worker>) โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโค โโโโโโค <Promise> process(<Task>) โ
โโโโโโค <Promise> process(<Task>) โ โ โฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ
โ โ <string[]> getDescriptionTypes() โ โ
โ โฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ โ
โ โ
โ โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโดโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โญโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฎ
โ โ โโโโโค (i) Task\Description โ
โ โญโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฎ โ โ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโค
โ โโโโโค (i) Task โโโโโ โ โฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ
โ โ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโค โ
โ โ โ <Description> getDescription() โโโโโโโโโ โญโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฎ
โ โ โ <Status> getStatus() โโโโโโโโโโโโโค (i) Task\Status โ
โ โ โ <History> getHistory() โโโโโโโโโ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโค
โ โ โฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ โ โ __construct(<string>) โ
โ โ โ โ <string> getStatus() โ
โ โญโโโโโโโโโโโโโโโโโโโโโโโโโโโฎ โ โ โ <string> __toString() โ
โ โ (i) Pool โ โ โ โฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ
โ โโโโโโโโโโโโโโโโโโโโโโโโโโโโค โ โ
โโโโโโค <Pool> addTask(<Task>) โ โ โ
โ <Task> getTask() โโโโโ โญโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฎ โ
โ <Status> getStatus() โโโโโโโโโค (i) Pool\Status โ โ
โฐโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโค โ
โ __construct(<string>) โ โ
โ <string> getStatus() โ โ
โ <string> __toString() โ โ
โฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ โ
โ
โ
โ
โญโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฎ โ
โ (i) Task\History โโโโโโโโโโโโโโโโโโโโโโโโ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโค
โโโโโโโโโโโโค <History> addEvent(<Event>)โ
โ โ <Event[]> getEvents() โโโโโโโโโโโโโ
โ โ <Event> getLastEvent() โโโโโโโโโโโโโค
โ โฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ โ
โ โ
โ โญโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฎ โ
โโโโโโโค (i) Task\History\Event โโโโโโโ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโค
โ <Event> startEvent() โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโค
โโโโโฌโโโโโโโค <Event> endEvent(<Result>, <Reason>) โ
โ โ โ <float> getStartTime() โ
โ โ โ <float> getEndTime() โ
โ โ โ <Result> getResult() โโโโโโโโโโโ
โ โ โ <Reason> getReason() โโโโโโโ โ
โ โ โ <string> __toString() โ โ โ
โ โ โฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ โ โ
โ โ โ โ
โ โ โญโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฎ โ โ
โ โโโโโโโโโโโค (i) Task\History\Reason โโโโโโโโโโโ โ
โ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโค โ
โ โ __construct(<string>) โ โ
โ โ <string> getReason() โ โ
โ โ <string> __toString() โ โ
โ โฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ โ
โ โ
โ โญโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฎ โ
โโโโโโโโโโโโโโโค (i) Task\History\Result โโโโโโโโโโโโโโโ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโค
โ __construct(<string>) โ
โ <string> getResult() โ
โ <string> __toString() โ
โฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ
Task
A task represents a piece of work that needs to happen. It tells you the history of the task, its current status, and what it wants to happen, but does not specify how to do it.
โญโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฎ
โ (i) Task โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโค
โ <Description> getDescription() โ โ Description tells a worker what needs to happen
โ <Status> getStatus() โ โ The current status of the Task: 'new', 'in progress', 'complete', or 'deferred'
โ <History> getHistory() โ โ The history of the Task so far
โฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ
Task - Description
Description is an empty interface simply used for control. It should be extended to provide the information require for a specific task.
โญโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฎ
โ (i) Task\Description โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโค
โฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ
For example, if you wanted a worker that could move files, you could define a MoveFile interface. The interface tells
you where the file is now, and where it should be. Your worker should then add the interface name (MoveFile
) to it's
list of Descriptions it knows how to deal with, provided by Worker::getDescriptionTypes()
.
โญโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฎ
โ (i) MoveFile : Description โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโค
โ <string> fromLocation() โ
โ <string> toLocation() โ
โฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ
Task - Status
The task maintains a reference in the Task Pool until it is complete. At any point a Task may be asked for it's Status. A task may have one of four statuses.
new
: The tasks has not been touched since it was createdin progress
: The task has been removed from the pool to be processedcomplete
: The task has been processed. This does not specify whether the task succeeded or failed, that is covered by the [Result][#task-history]deferred
: The task has been attempted previously but for whatever reason has been put back in the queue.
โญโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฎ
โ (i) Task\Status โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโค
โ __construct(<string>) โ โ Initialise the Status with: 'new', 'in progress', 'complete', or 'deferred'
โ <string> getStatus() โ โ The string representation of the status
โ <string> __toString() โ โ must return getStatus()
โฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ
Task - History
The history is simply a collection of Events
โญโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฎ
โ (i) Task\History โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโค
โ <History> addEvent(<Event>)โ โ Add a new event to the history
โ <Event[]> getEvents() โ โ Returns an array of all events
โ <Event> getLastEvent() โ โ Returns the last event or null if there is nothing in the history
โฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ
Task - History - Event
A single event in the tasks history. A new event should be created when the Task leaves the Pool to be processed. The event is completed when the Pool is asked to complete or defer the task.
โญโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฎ
โ (i) Task\History\Event โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโค
โ <Event> startEvent() โ โ Events should only be created through this static method
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโค
โ <Event> endEvent(<Result>, <Reason>) โ โ End the event with a Result, and optionally Reason
โ <float> getStartTime() โ โ Get the event start time. This should be the time the event was created
โ <float> getEndTime() โ โ Get the end time or null if it's in progress
โ <Result> getResult() โ โ Always returns a Result, though it defaults to 'incomplete'
โ <Reason> getReason() โ โ Always returns a Reason, though it's empty by default
โ <string> __toString() โ โ Should return a string representation of the event for logging purposes
โฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ
Task - History - Result
The result of trying to process the Task, recorded against an Event in History.
โญโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฎ
โ (i) Task\History\Result โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโค
โ __construct(<string>) โ โ Initialise the Result with a value: 'succeeded', 'failed' or 'incomplete'
โ <string> getResult() โ โ The string representation of the result: 'succeeded', 'failed' or 'incomplete'
โ <string> __toString() โ โ must return getResult()
โฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ
Task - History - Reason
The reason for the Result of trying to process the Task, recorded against an Event in History. This is optional and can be any string. It is mostly useful for logging failures.
โญโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฎ
โ (i) Task\History\Reason โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโค
โ __construct(<string>) โ โ Initialise the Reason with any string value
โ <string> getReason() โ โ The string representation of the Reason
โ <string> __toString() โ โ must return getReason()
โฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ
Pool
The Task Pool is designed to store and retrieve tasks. It could represent a queue, a stack, a heap or something else.
โญโโโโโโโโโโโโโโโโโโโโโโโโโโโฎ
โ (i) Pool โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโค
โ <Pool> addTask(<Task>) โ โ returns a reference to itself for chaining
โ <Task> getTask() โ โ get the next Task from the pool
โ <Status> getStatus() โ โ tells you if the pool has tasks 'pending' or is 'empty'
โฐโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ
Pool - Status
The State of the Task Pool is represented by the Status Value Class. It could be in two states.
pending
There are tasks waiting to be processedempty
There are no tasks waiting to be processed
Note: Tasks with the status in progress
or complete
should not be considered waiting.
โญโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฎ
โ (i) Pool\Status โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโค
โ __construct(<string>) โ โ Initialise the Status with: 'pending' or 'empty'
โ <string> getStatus() โ โ The string representation of the status
โ <string> __toString() โ โ must return getStatus()
โฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ
Worker
Workers are where the Tasks are processed. They may or may not be asynchronous and therefore should always return a Promise.
Workers may also be able to handle multiple types of Task Descriptions, and will therefore always return an array of strings. The best practice, however, should be to have one worker per Task Description
โญโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฎ
โ (i) Worker โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโค
โ <Promise> process(<Task>) โ โ Workers always return Promises, regardless of whether they are asynchronous.
โ <string[]> getDescriptionTypes() โ โ This should return an array of Descriptions Types the worker knows how to handle.
โฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ
Mediator
The mediator is responsible for taking a task and passing it to the correct worker.
โญโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฎ
โ (i) Mediator โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโค
โ <Mediator> addWorker(<Worker>) โ โ Inform the mediator about a Worker. Returns a reference to itself
โ <Promise> process(<Task>) โ โ Pass a task. This will return a promise from a Worker to do the task or throw an
โฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ exception if no appropriate Worker was found.
Promise
Workers return React Promises. See the documentation here: https://github.com/reactphp/promise
Worker Modules
You can create a module of workers for Masonry using the WorkerModule class. It is a cross between a Worker and a Mediator mediating between it's internal workers, but exposing itself to other mediators as a worker.
โญโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฎ
โ (i) WorkerModule : Mediator, Worker โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโค
โ __construct([<Worker>]) โ
โ <Mediator> addWorker(<Worker>) โ
โ <Promise> process(<Task>) โ
โ <string[]> getDescriptionTypes() โ
โฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ