Download the PHP package deefour/interactor without Composer
On this page you can find all versions of the php package deefour/interactor. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Informations about the package interactor
Interactor
Simple PHP Service Objects. Inspired by collectiveidea/interactor.
Getting Started
Run the following to add Interactor to your project's composer.json
. See Packagist for specific versions.
>=PHP5.6.0
is required.
What is an Interactor
An interactor is a simple, single-purpose object.
Interactors are used to encapsulate your application's business logic. Each interactor represents one thing that your application does.
An interactor
- Extends
Deefour\Interactor\Interactor
- Implements a
call()
method
As a simple example, the below interactor creates a new Car
.
Context
An interactor runs based on a given context. The context contains the information the interactor needs to do its work. An interactor may affect its passed context, providing data from within the interactor back to the caller.
All contexts extend the Deefour\Transformer\MutableTransformer
from the deefour/transformer
package. The MutableTransformer
provides conveient access and mutation of the underlying data, including but not limited to implementations of ArrayAccess
and JsonSerializable
.
Accessing the Context
An interactor's context can be accessed via the context()
method.
Modifying the the Context
An interactor can add or modify the context.
This can be very useful to provide data back to the caller.
Permitted Attributes
Performing safe mass assignment is easy thanks to the MutableTransformer
's only()
method.
Specific Context Requirements
The default context constructor expects a single array of attributes as key/value pairs.
An interactor often requires specific data from the provided context. For example, a CreateCar
interactor might expect to assign an owner to the Car
it creates. A context class should be created specifically for this Interactor requiring a user be provided during instantiation.
The CreateCar
interactor should expect an instance of this new CarContext
during instantiation
The Context Factory
While instantiating contexts manually is the norm, the ContextFactory
is a useful alternative in certain circumstances. Pass a fully qualified name of the context to be instantiated along with a set of attributes/parameters to the create()
method.
Explicitly specifying an 'attributes'
parameter isn't necessary. Any keys in the array of source data passed to the factory that do not match the name of a parameter on the constructor will be pushed into an $attributes
parameter. If you provide an 'attributes'
parameter manually in addition to extra data, the extra data will be merged into the $attributes
array.
Note: Taking advantage of this requires an
$attributes
parameter be available on the constructor of the context class being instantiated through the factory.
Status
The state of an interactor is considered passing or failing. A context holds the current state in a $status
proprerty. This library provides a Success
and Error
status. Contexts are given a Success
status by default.
Failing the Context
An interactor can be considered a failure when something goes wrong during it's execution. This is done by marking the context as having failed.
A message can be provided to explain the reason for the failure.
Failing a context causes a Deefour\Interactor\Exception\Failure
exception to be thrown.
If an exception is provided it will be thrown after copying it's message over to the Error
status set on the context.
Checking the Status
You can ask if the state is currently successful/passing.
Usage
Within a controller, implementing the car creation through the CreateCar
interactor might look like this.
Dispatching Interactors
A Deefour\Interactor\DispatchesInteractors
trait can be included in any class to reduce the creation and execution of an interactor to a single method call. In the example below, this trait will
- Resolve a new
CarContext
instance using the providedUser
,'make'
, and'model'
- Instantiate a new
CreateCar
instance with the newly createdCarContext
- Execute the
call()
method on the interactor - Return the context
Organizers
Complex scenarios may require the use of multiple interactors in sequence. If a registration form asks for a user's email, password, and VIN of their car, the submission might register a new user account and create a new vehicle for the user based on the VIN. These two actions are best broken up into CreateUser
and CreateVehicle
interactors. An organizer can be used to manage the execution of these interactors.
Combining Interactors via an Organizer
To create an organizer, extend Deefour\Interactor\Organizer
and implement an organize()
method that pushes interactors onto the queue. The call()
method for an organizer is implemented by the library. Like a standard interactor, an organizer can require a specific context by type-hinting the constructor.
The enqueue()
method accepts a callable
which should return an interactor instance. The callables are executed in a first-in-first-out manner. Each callable receives the organizer's context along with the context of the previously executed interactor.
The deferred instantiation allows for information only available after the execution of a previous interactor to be used when creating the current interactor.
Executing an Organizer
An organizer is executed like any other interactor. Call the call()
method to kick things off after instantiation.
Organizer Failure and Rollback
If a failure occurs during the execution of an organizer, rollback()
will be called on each interactor that ran successfully prior to the failure, in reverse order. Override the empty rollback()
method on Deefour\Interactor\Interactor
to take advantage of this.
Note: The
rollback()
method is not called when an interactor is executed on it's own, though it can be called manually by testing for failure on the context.
Integration With Laravel 5
A job in Laravel 5 can be treated as in interactor or organizer. The handle()
method on a job called through Laravel's job dispatcher supports dependency injection through the service container. An implementation of the CreateCar
interactor that takes advantage of dependency injection and Laravel's job dispatcher might look like this:
Laravel needs to be told to to use it's own dispatch()
method instead of the one provided by this library. This allows both interactors and vanilla Laravel jobs can be dispatched.
Note: Interactors can even implement Laravel's
Illuminate\Contracts\Queue\ShouldQueue
to have execution deferred!
Contribute
- Issue Tracker: https://github.com/deefour/interactor/issues
- Source Code: https://github.com/deefour/interactor
Changelog
2.0.0 - January 26, 2017
- Rewritten API for organizers.
1.2.0 - October 16, 2016
- Exceptions can now be passed to a context's
fail()
method. A passed exception will be thrown instead of a newDeefour\Interactor\Exception\Failure
. Thanks to @gpassarelli in #6.
1.1.0 - October 19, 2015
call()
is no longer abstract; it's left as a blank stub to be overridden. This eliminates the need to definecall()
when another method is being used for business logic (ie. when using ahandle()
to work with Laravel's command bus).- Breaking Chang The
DispatchesInteractors
trait no longer resolves interactors through the service container.- The trait can now be used outside the context of Laravel. A basic
dispatch()
method has been implemented to execute thecall()
method on the interactor. - Within the context of Laravel, all dependency injection should be done on the
handle()
method, just like any other Laravel job. Constructor injection is no longer supported. - Laravel must be told to use the
Illuminate\Foundation\Bus\DispatchesJobs::dispatch()
method when using both Laravel's job dispatcher and this library's interactor dispatcher. See Integration with Laravel above for more information.
- The trait can now be used outside the context of Laravel. A basic
1.0.0 - October 7, 2015
- Release 1.0.0.
0.7.0 - June 21, 2015
- New
Organizer
andCompositeContext
for grouping interactors together.
0.6.2 - June 5, 2015
- Now following PSR-2.
0.6.0 - May 30, 2015
- New
ContextFactory
for creating context objects. - Now has
deefour/transformer
as dependency. Context
now extedsMutableTransformer
. This class no longer implementsArrayAccess
directly.attributes()
method onContext
has been removed. Useall()
orraw()
(for non-transformed version of attributes) instead.Interactor
has been simplified, using only type-hints to enforce proper context for an interactor.
0.5.0 - May 25, 2015
- Now suggesting
deefour/transformer
be required. If available, the context will be wrapped in aMutableTransformer
, providing all the functionality available indeefour/transformer
transparently on the context object. - New
__isset()
implementation and better support for null context values. - Improved code formatting.
0.4.4 - February 20, 2015
- Added
permit()
method to provide a watered down version of rails/strong_parameters whitelisting against the contents of aContext
.
0.4.0 - February 1, 2015
- Move much of the API out of the interactor and into the context
- Changed
perform()
tocall()
- Add new trait with
dispatchInteractor()
method.
0.3.0 - January 3, 2015
- Refactor, striping out dependency on and support for Illuminate components.
- Compatibility changes to work easily with Laravel 5's new command bus and event handlers.
- Inverting resolution lookup; contexts now resolve interactors instead of the other way around.
0.2.0 - October 7, 2014
- Automatic context resolution from instantiated interactor.
0.1.0 - October 2, 2014
- Initial release
License
Copyright (c) 2017 Jason Daly (deefour). Released under the MIT License.