Updated docs

Author: adrianmiu

docs/1_callable_list.md docs/1_callable_collection.mddocs/1_callable_list.md renamed to docs/1_callable_collection.md

@@ -6,10 +6,10 @@ title: What are callable collection in Sirius\Invokator?
 
 In the `Sirius\Invokator` items in the callable collections are organized by priority. By default, the priority is determined by the order the callables are added to the collection. The callables are executed in the order of their priority.
 
-A **callable** is something that can be executed directly or after being interpreted by the [invoker](2_the_invoker.md). For example the `Invoker` class that comes with this library can recognize and execute callables in the form of 
-`SomeClass@someMethod`
+A **callable** is something that can be executed directly or after being interpreted by the [invoker](4_the_invoker.md). 
+For example the `Invoker` class that comes with this library can recognize and execute callables in the form of `SomeClass@someMethod`
 
-Even though callable collections may have different purposes (middleware, events etc), a collection is defined in a single way. 
+Even though callable collections may have different purposes (middleware, events, etc.), a collection is defined in a single way. 
 
 Below it's an example for a collection designed to run as a pipeline that process a piece of text
 
@@ -63,9 +63,11 @@ $processor = new PipelineProcessor($invoker);
 $processor->processCollection($callables, ' world '); 
 
 // this will
-// 1. create string `HELLO WORLD`,
-// 2. Write an info message to the logger
-// 3. send it to a SlackChannel
+// 1. trim the parameter => `world`
+// 2. concatenate with "hello " => `hello world`
+// 3. make the string uppercase => `HELLO WORLD`,
+// 4. write the string as an info message to the logger
+// 5. send the string to a SlackChannel
 ```
 
 Each type of callables processor has its own quirks that you can learn on the next page.

docs/2_3_command_bus.md

@@ -39,7 +39,7 @@ $bus->register(CreateProductCommand::class, 'SomeClass@execute');
 You can add middlewares at any point in time, before or after registering the command handlers.
 
 ```php
-$bus->addMiddleware(CreateProductCommand::class, 'CommandMiddleware@execute');
+$bus->addMiddleware(CreateProductCommand::class, 'CommandMiddleware@execute', 100 /* priority (optional) */);
 ```
 
 [Next: Actions a la Wordpress](2_4_wordpress_actions.md)

docs/2_3_event_dispatcher.md

@@ -19,10 +19,13 @@ $dispatcher = new Dispatcher($listenerProvider, $invoker);
 $listenerProvider->subscribeTo(Event::class, 'some_callable', 0);
 $listenerProvider->subscribeOnceTo(Event::class, 'some_callable', 0);
 
-// if you use the Sirius\Invokator\Event\ListenerProvider
+// if you use the \Sirius\Invokator\Event\ListenerProvider
 // the same results as above can also be achieved with
 $dispatcher->subscribeTo(Event::class, 'some_callable', 0);
 $dispatcher->subscribeOnceTo(Event::class, 'some_callable', 0);
+
+// dispatch the event
+$dispatcher->dispatch(new Event());
 ```
 
 ### Named events

docs/2_3_middlewares.md

@@ -18,14 +18,14 @@ use Sirius\Invokator\Processors\MiddlewareProcessor;
 $invoker = new Invoker($psr11Container);
 $processor = new MiddlewareProcessor($invoker);
 
-$processor->get('dispatcher')
+$processor->get('http_handler')
           ->add('CsrfCheckMiddleware') 
           ->add('TrimStringsMiddleware')
           ->add('AuthMiddleware')
           ->add('CacheMiddleware')
           ->add('RouterMiddleware');
 
-$processor->process('dispatcher', new HttpRequest);
+$processor->process('http_handler', new HttpRequest);
 ```
 
 While this example is for HTTP middleware, it does not implement the [PSR-15 middleware specifications](https://www.php-fig.org/psr/psr-15/) as it does not enforce their respective signatures. It would be up to your app to enforce those restrictions

docs/2_4_wordpress_actions.md

@@ -6,7 +6,7 @@ title: Actions a la Wordpress
 
 This processor is similar to the "Simple callables processor" with the difference that you also have to specify a limit for the arguments passed to each callable.
 
-This means that the callables do not have to have the same signature as for the SimpleCallables processor. This processor is just a convenience as the same result could be been achieved using the ['limit_arguments' modifier](4_callable_modifiers.md)
+This means that the callables do not have to have the same signature as for the SimpleCallables processor. This processor is just a convenience as the same result could be been achieved using the ['limit_arguments' modifier](3_callable_modifiers.md)
 
 #### Use case
 
@@ -17,17 +17,17 @@ use Sirius\Invokator\Processors\ActionsProcessor;
 $invoker = new Invoker($psr11Container);
 $processor = new ActionsProcessor($invoker);
 
-$processor->add('save_post', 'validate_taxonomies', 0, 2); // callback, priority, no of arguments passed 
-$processor->add('save_post', 'validate_acf_fields', 0, 2);
+$processor->add('save_post', 'validate_taxonomies', 0, 2); // callback, priority, number of arguments passed 
+$processor->add('save_post', 'validate_acf_fields', 1, 2);
 $processor->add('save_post', 'check_permissions', 10, 1);
 
 $processor->process('save_post', $postID, $wpPost, $update);
 ```
 
-**Attention!** The processor's `get()` and `add()` method return the Stack object, so you can't chain callables with arguments limit. For example the code below doesn't work as you might expect
+**Attention!** The processor's `get()` and `add()` method return the callables collection, so you can't chain callables with arguments limit. For example the code below doesn't work as you might expect
 ```php
-$processor->add('save_post', 'validate_taxonomies', 0, 2) // this returns the collection
-          ->add('validate_acf_fields', 0, 2); // this won't place a limit on the arguments for the 'validate_acf_fields' function
+$processor->add('save_post', 'validate_taxonomies', 0, 2) // this returns the callables collection
+          ->add('validate_acf_fields', 0, 2); // this won't place a limit on the arguments for the 'validate_acf_fields' function since the callables is returned by the first add() call
 ```
 
 [Next: Filters a la Wordpress](2_5_wordpress_filters.md)

docs/2_5_wordpress_filters.md

@@ -27,7 +27,7 @@ $processor->process('the_title', $postTitle, $postID);
 
 ```php
 $processor->add('the_title', 'add_category_name', 0, 2) // this returns the collection
-          ->add('add_site_name', 0, 2) // this won't place a limit on the arguments for the 'add_site_name' function
+          ->add('add_site_name', 0, 2) // this won't place a limit on the arguments for the 'add_site_name' function since the callables is returned by the first add() call
 ```
 
 [Next: Custom callable processors](2_6_custom_processors.md)

docs/2_6_custom_processors.md

@@ -10,5 +10,6 @@ If you extend the `SimpleCallablesProcessor` you only need to implement the `pro
 
 Here are some ideas:
 1. pipelines where all the callbacks receive the same arguments and where the result of a callback becomes the first argument in the list. It would be similar to the "Filters processor" but without having to specify the limit for the arguments.
+2. HTTP middleware implementation of the PSR-15 standard. It would be similar to the "Middlewares processor" but with the restriction that all the callables should have the same signature.
 
 [Next: callable modifiers](3_callable_modifiers.md)

docs/2_callable_processors.md

@@ -10,13 +10,12 @@ Callable processors are objects that have 3 objectives:
 3. To process collections stored in the registry via `$processor->process('callables_identifier', $param_1, $param_2)`
 4. To process callable collections constructed separately via `$processor->processCollection($previouslyConstructedCollection, $param_1, $param_2)` 
 
-The processors depend on the [invoker](3_the_invoker.md) to actually execute the callbacks.
+The processors depend on the [invoker](4_the_invoker.md) to actually execute the callbacks.
 
 The `Sirius\Invokator` library comes with 5 callable processors/runners
 1. [simple collection](2_1_simple_collection.md)
 2. [pipelines](2_2_pipelines.md)
 3. [middlewares](2_3_middlewares.md)
 4. [actions a la Wordpress](2_4_wordpress_actions.md)
 5. [filters a la Wordpress](2_5_wordpress_filters.md)
-
-You can also implement pretty easily your own [custom callables](2_6_custom_processors.md)
+6. [custom processors](2_6_custom_processors.md)

docs/3_callable_modifiers.md

@@ -24,15 +24,17 @@ use Sirius\Invokator\Processors\SimpleStackProcessor;
 $invoker = new Invoker($psr11Container);
 $processor = new SimpleStackProcessor($invoker);
 
-$processor->get('collection')
+$processor->get('callables_collection')
           ->add(limit_arguments(function($param_1, $param2) {
-              return 'something'
+              return 'something';
           }, 2))
           ->add(limit_arguments('Service@method', 1));
 
-$processor->process('collection', $param_1, $param_2, $param_3, $param_4);
+$processor->process('callables_collection', $param_1, $param_2, $param_3, $param_4);
 ```
 
+Even though this processor will receive 4 arguments, the callables will only receive 2 and 1 arguments respectively.
+
 This modifier is used by the [actions processor](2_4_wordpress_actions.md) and the [filters processor](2_5_wordpress_filters.md)
 
 ## The "once" modifier
@@ -45,13 +47,13 @@ It is useful for an events system where you want a particular listener to be exe
 
 ```php
 use function Sirius\Invokator\once;
-$processor->get('add')
+$processor->get('callables_collection')
           ->add(once(function($param_1, $param2) {
             return $param_1 + $param2
           }));
 
-$processor->process('event', 2 + 3);  // this returns 5
-$processor->process('event', 8 + 7);  // this STILL returns 5
+$processor->process('callables_collection', 2, 3);  // this returns 5
+$processor->process('callables_collection', 8, 7);  // this STILL returns 5
 ```
 
 ## The "wrap" modifier
@@ -62,33 +64,36 @@ This can be used to override how the callable is actually being executed by pass
 
 ```php
 use function Sirius\Invokator\wrap;
-$processor->get('collection')
+$processor->get('callables_collection')
           ->add(wrap('Service@method', function(callable $callable) use ($param_3, $param_4) {
               return $callable($param_3, $param_4);
           }, 2));
 
-$processor->process('collection', $param_1, $param_2);
-// the `Service@method` function will actually receive $param_3 and $param_4 as arguments instead of $param_1 and $param_2
+$processor->process('callables_collection', $param_1, $param_2);
 ```
 
+The `Service@method` function will actually receive $param_3 and $param_4 as arguments instead of $param_1 and $param_2
+
 ## The "with arguments" modifier
 
-This modifier can be used when you have a callable that has a specific signature, and you don't want to change its signature nor do you want to wrap it inside an anonymous function (eg: because you want to serialize the collection)
+This modifier can be used when you have a callable that has a specific signature, and you don't want to change its signature nor do you want to wrap it inside an anonymous function (eg: because you might need to serialize the collection)
 
 ```php
 use function Sirius\Invokator\with_arguments;
 use function Sirius\Invokator\ref;
 use function Sirius\Invokator\arg;
-$processor->get('collection')
+$processor->get('callables_collection')
           ->add(with_arguments('Service@method', [arg(0), 'value', ref('SomeClass'), arg(1)]);
 
-$processor->process('collection', $param_1, $param_2);
-
-// This is the same as calling Service@method($param_1, 'value', $container->get('SomeClass'), $param_2)
+$processor->process('callables_collection', $param_1, $param_2);
+// 
 ```
+
+This is the same as calling `Service@method($param_1, 'value', $container->get('SomeClass'), $param_2)`
+
 ## The "resolve" modifier
 
-Some callables might have dependencies on other services, and you might not know them while you call them or you might not want to be forced to use `ref()` them. In this case you can use the `resolve()` modifier.
+Some callables might have dependencies on other services, and you might not know them while you call them, or you might not want to be forced to use `ref()` them. In this case you can use the `resolve()` modifier.
 
 The `resolve()` modifier works with the `arg()` and `ref()` utilities.
 
@@ -101,9 +106,10 @@ $processor->get('collection')
           ->add(resolve('Service@method', ['param_1' => arg(0), 'param_3' => 20]);
 
 $processor->process('collection', 10);
-// $param_2 will be a
 ```
 
+This will call `Service@method(10, $container->get('SomeClass'), 20)`
+
 You will learn about the `arg()` and `ref()` functions on the [invoker](4_the_invoker.md) page
 
 [Next: The callable invoker](4_the_invoker.md)