Add events_example module to demonstrate subscribing to and dispatching events

Copy edit review only. (Code not reviewed.)

1. +++ b/events_example/src/Event/IncidentEvents.php
   @@ -0,0 +1,55 @@
   + * In this example we're defining one new event;
   

   Use colon (:) instead of a semi-colon.

2. +++ b/events_example/src/Event/IncidentEvents.php
   @@ -0,0 +1,55 @@
   + * incident is reported. If you're application dispatches more than one event
   

   Change compound "you're" to possessive "your". "If your application..."

3. +++ b/events_example/src/Event/IncidentEvents.php
   @@ -0,0 +1,55 @@
   + * constant for each. Group like related events together with a single class,
   

   Seems like there's an extra unnecessary word. My suggestion: "Group related events together..." (Omit the word "like".)

4. +++ b/events_example/src/EventSubscriber/EventsExampleSubscriber.php
   @@ -0,0 +1,108 @@
   +    // unique task/concept rather than just creating a catch all class for all
   

   Hyphenate "catch-all".

5. +++ b/events_example/src/EventSubscriber/EventsExampleSubscriber.php
   @@ -0,0 +1,108 @@
   +    // the code responsible for dispatching the event. This way if for example
   

   Add commas for phrasing: "This way, if, for example,"...

6. +++ b/events_example/src/EventSubscriber/EventsExampleSubscriber.php
   @@ -0,0 +1,108 @@
   +    // here https://api.drupal.org/api/drupal/core%21core.api.php/group/events/8.2.x.
   

   Add colon after "here:" and possibly put URL on a new line for readability and line-length.

Great! Also, just copy edited the issue title.

Example still needs a code review.

Thanks... Glad to see this example.

A few coding standards errors:

$ ../../vendor/bin/phpcs -ps events_example/
WW.E..


FILE: ...pj2/drupal/modules/examples/events_example/events_example.module
----------------------------------------------------------------------
FOUND 0 ERRORS AND 2 WARNINGS AFFECTING 2 LINES
----------------------------------------------------------------------
 27 | WARNING | Line exceeds 80 characters; contains 83 characters
    |         | (Drupal.Files.LineLength.TooLong)
 52 | WARNING | Line exceeds 80 characters; contains 82 characters
    |         | (Drupal.Files.LineLength.TooLong)
----------------------------------------------------------------------


FILE: ...pal/modules/examples/events_example/src/Event/IncidentEvents.php
----------------------------------------------------------------------
FOUND 0 ERRORS AND 2 WARNINGS AFFECTING 2 LINES
----------------------------------------------------------------------
  4 | WARNING | [x] Unused use statement
    |         |     (Drupal.Classes.UnusedUseStatement.UnusedUse)
 29 | WARNING | [ ] Line exceeds 80 characters; contains 83
    |         |     characters (Drupal.Files.LineLength.TooLong)
----------------------------------------------------------------------
PHPCBF CAN FIX THE 1 MARKED SNIFF VIOLATIONS AUTOMATICALLY
----------------------------------------------------------------------


FILE: ...s/events_example/src/EventSubscriber/EventsExampleSubscriber.php
----------------------------------------------------------------------
FOUND 1 ERROR AFFECTING 1 LINE
----------------------------------------------------------------------
 3 | ERROR | [x] Namespaced classes, interfaces and traits should not
   |       |     begin with a file doc comment
   |       |     (Drupal.Commenting.FileComment.NamespaceNoFileDoc)
----------------------------------------------------------------------
PHPCBF CAN FIX THE 1 MARKED SNIFF VIOLATIONS AUTOMATICALLY
----------------------------------------------------------------------

Some review-y stuff:

1. +++ b/events_example/events_example.services.yml
   @@ -0,0 +1,16 @@
   +  events_example_subscriber:
   

   Let's add a kernel test that just grabs this service from the container, to verify that it's reachable.

2. +++ b/events_example/src/Event/IncidentEvents.php
   @@ -0,0 +1,55 @@
   +namespace Drupal\events_example\Event;
   +use Drupal\Core\Config\ConfigCrudEvent;
   

   Add a line between these.

3. +++ b/events_example/src/Event/IncidentEvents.php
   @@ -0,0 +1,55 @@
   +final class IncidentEvents {
   

   Explain in the class docblock why this class is final.

4. +++ b/events_example/src/EventSubscriber/EventsExampleSubscriber.php
   @@ -0,0 +1,109 @@
   +// By convention, classes subscribing to an event live in the
   +// Drupal/{module_name}/EventSubscriber namespace.
   

   Move this to the class docblock.

5. +++ b/events_example/src/EventSubscriber/EventsExampleSubscriber.php
   @@ -0,0 +1,109 @@
   +class EventsExampleSubscriber implements EventSubscriberInterface {
   +  use StringTranslationTrait;
   

   Add a blank line between these.

Some editorial review:

1. +++ b/events_example/events_example.module
   @@ -0,0 +1,70 @@
   + * communicate with each other. One system component or module dispatches the
   + * event at an appropriate time; many events are dispatched during every
   + * request. Other system components or modules can register as event
   + * subscribers; when an event is dispatched, a method is called on each
   + * registered subscriber, allowing each one to react.
   

   This is a dense paragraph... I'd say about half of it should be another paragraph explaining that modules can dispatch events but they don't need to, and can just subscribe to existing events.

2. +++ b/events_example/events_example.module
   @@ -0,0 +1,70 @@
   + * This allows modules to alter and extend other systems without the need to
   + * modify the original code.
   

   Events don't actually allow modules to alter anything, or at least shouldn't. It's just a ping that something happened.

3. +++ b/events_example/events_example.module
   @@ -0,0 +1,70 @@
   + * Subscribe to an event in order to react whenever that event occurs.
   + *
   + * This requires:
   

   Who's subscribing? Also condense these to one line.

4. +++ b/events_example/events_example.module
   @@ -0,0 +1,70 @@
   + * Dispatch an event to allow other code to react to what your code is doing.
   + *
   + * This requires:
   

   Who's dispatching? Also condense these to one line.

5. +++ b/events_example/events_example.module
   @@ -0,0 +1,70 @@
   + * https://drupalize.me/blog/201502/responding-events-drupal-8 Responding to
   

   Yay drupalize.me. :-)

6. +++ b/events_example/src/Event/IncidentEvents.php
   @@ -0,0 +1,55 @@
   + * It is best practice define the unique names for events as constants on a
   + * static class. This provides a place for documentation of the events. As well
   ...
   +final class IncidentEvents {
   

   Docs say it should be static, but it's not.

7. +++ b/events_example/src/Event/IncidentEvents.php
   @@ -0,0 +1,55 @@
   + * Additionally the docblock for each event should contain an "@Event" tag. This
   

   I think @Event isn't really 'additionally' important. :-) It should come first in describing how this works.

+++ b/events_example/src/EventSubscriber/EventsExampleSubscriber.php
@@ -0,0 +1,108 @@
+      // If there are other subscribers that have not been called yet this will
+      // cause them to be skipped.

No fear when batman is here. No need to call the police :) first thought that came in mind while reviewing it.

Testbot issues aside, +1 on the changes and the patch does in fact apply. Thanks.

Let's see if we can kick the testbot into behaving...

OK, the testbot is happier now. ::unhappy glances at the DA::

Committed, pushed. :-)

Thanks!