-
Notifications
You must be signed in to change notification settings - Fork 0
Using Scribes Event Driven Design
Before and after everything Scribe does, an event is fired. The event contains all the critical information and the data used by Scribe to process the request. Classes you create to work with Scribe (Controllers, Repositories, and Entities) all will automatically detect on methods added to them, and call these methods as needed. Additionally, you can create your own event subscribers that listen to these events.
This Event Driven Design means you can easily insert your own code into any part of Scribes functionality (All the way from Controller Events, to Repository Events, to Entity Events). Your code can manipulate any of the inputs or outputs of Scribe allowing you complete control to extend and modify Scribes functionality without having to directly modify or extend any of its base functionality.
Entities, Repositories, and Controllers in Scribe all have their own event managers, and they will automatically add themselves as listens to the event managers.
This allows you to easily just add a method with the appropriate name (such as on prePersist) to a class and it will be fired.
You also can make and assign your own listener objects to the Entities, Repositories, and Controllers.
Entities and Repositories have a Doctrine 2 Event Manager associated with them. You can access it by calling the method "getEventManager". Then you can add an event subscriber to the dedicated Event Manager by calling "addEventSubscriber({object})" on the Event Manager.
See Doctrine docs here for more details:
Controllers use standard Laravel events. So to subscribe to controller events just call: "Event::subscribe{object});"
See the Laravel documentation here:
All Scribe events have an ArrayObject of event arguments you can access. Any changes you make to these event arguments will be used within the application. In other words, by changing the data on the ArrayObject of arguments, you change the data Scribe will be used internally as part of its processing. This lets you insert your own logic via events to modify how Scribe behaves, as well as using events to trigger your own custom behaviors.
Controller Events receive one argument of "$event". Call "$event->getEventArgs()" to get the ArrayObject that holds the arguments for the event.
Listeners to controller events (including those that can be placed as methods on the controller its self) are as follows.
- onInit -- runs before any controller action is called
- onPreIndex -- runs before index action is called
- onPostIndex -- runs after index action is called
- onPreStore -- runs before store action is called
- onPostStore -- runs after store action is called
- onPreShow -- runs before show action is called
- onPostShow -- runs after show action is called
- onPreUpdate -- runs before update action is called
- onPostUpdate -- runs after update action is called
- onPreDestroy -- runs before destroy action is called
- onPostDestroy -- runs after destroy action is called
- self -- (ControllerArrayHelperContract) this is the helper object that stores and manipulates all the information about the controller config.
- query -- (Array) the frontend filter query used to filter index defaults.
- frontEndOptions -- (Array) the options passed from the front end.
- controllerOptions -- (Array) the current options set on the controller.
- overrides -- (Array) option overrides that will be passed to the repository.
- controller -- (ControllerContract) the controller being called.
- result -- (Array) this is the result from the controller action, it will only be seen in event args that run on "Post".
These are identical to the Get Request args, however, instead of "query" they will contain:
- params -- (Array) the params that will be passed to the repository to create/update/delete resources.
Repositories fire the following events:
- preStart -- runs at the start of any create/read/update/delete call to the repository.
- preStop -- runs at the end of any create/read/update/delete call to the repository.
- preCreateBatch -- runs before a batch takes place
- preCreate -- runs before a single entity is manipulated.
- validateCreate -- runs before a single entity is manipulated, intended for validation of the params passed.
- verifyCreate -- runs before a single entity is manipulated, intended for verification of the params passed.
- processResultsCreate -- runs after an interaction with the database to give the developer the option to manipulate the results before returning them.
- postCreate -- runs after each create
- postCreateBatch -- runs after top level batch create finishes
Note: The following events are also dispatched, and work in an equivalent fashion to the "create" events above.
- preUpdateBatch
- preUpdate
- validateUpdate
- verifyUpdate
- processResultsUpdate
- postUpdate
- postUpdateBatch
- preDeleteBatch
- preDelete
- validateDelete
- verifyDelete
- processResultsDelete
- postDelete
- postDeleteBatch
All Repository Events will receive (GenericEventArgsContract) as an argument. Call "getArgs" on that object to get the ArrayObject of Event Args.
They will include the following:
- params -- (Array) these are the params that were passed to the method
- arrayHelper -- (ArrayHelperContract) this is the shared array helper used at all levels of the Scribe stack.
- configArrayHelper -- (QueryBuilderHelperContract) this is the array helper that stores the configuration for the repository.
- entity -- (EntityContract) The entity that is about to be operated on, only present in update and delete
- results -- (EntityContract[]) these are the results that will be returned by the method call.
- lastResult -- (EntityContract) the last entity made by the repo.
- self -- (RepositoryContract) this is the repository it's self.
- options -- (Array) these are the options that are set in the repository.
- optionOverrides -- (Array) these are the option overrides that were passed to the method call.
- entitiesShareConfigs -- (Boolean) whether or not entities should share configs (this is an internal optimization method, and generally need not be tampered with).
- frontEndOptions -- (Array) the options passed from the front end to the method call.
Entities fire the following events
- preSetField -- fires before a field value is set.
- preProcessAssociationParams -- fires before a association value is set.
- prePersist -- fires before an entity is persisted.
- postPersist -- fires after an entity is persisted.
Entity Events get the following arguments.
- params -- (Array) these will vary depending on the event being called
- configArrayHelper -- (EntityArrayHelperContract) this is the array helper that stores the configuration for the entity.
- arrayHelper -- (ArrayHelperContract) this is the shared array helper used at all levels of the Scribe stack.
- self -- (EntityContract) this is the entity it's self.
- fieldName -- (String) name of the filed being set.
- value -- (mixed) value of the feild being set.
- associationName -- (String) name of the association being set.
- values -- (mixed) values of the association being set.
Just gets the base params described above.
If you want your event listeners to context-sensitive, in the same way, you can set values in the config you have a few options.
- You could pass custom options via your config for the context in question and then detect those in your method that is listening for the event. The configArrayHelper key of the event args config gives you access to currently active config, so you can always call: getArray() on the config helper to see what the current settings are for the config.
- You can check getTTPath() on the "self" key of the event args. This will let you know what context path was passed to the operation, and then you can write conditional code based around that.