Merge branch '8.x-1.x' of ssh://git.drupal.org/project/examples into 8.x-1.x

Author: torenware

Diff for: STANDARDS.md

@@ -6,18 +6,18 @@ Examples uses mostly the same coding standards as Drupal core.
 If you see a discrepancy between the coding standards tools used by core and
 those used by Examples, please file an issue so that Examples can follow core.
 
-Examples uses the phpcs tool to allow for checking PHP coding standards. We also
-use eslint for JavaScript coding standards.
+Examples uses the `phpcs` tool to allow for checking PHP coding standards. We
+use the `drupal/coder` project for Drupal-specific coding standards.
 
-Examples has a `phpcs.xml.dist` file at the root of the project. This file
-specifies the current coding standards 'sniffs' which code in the project must
-pass.
+We also use `eslint` for JavaScript coding standards.
 
-The `phpcs.xml.dist` file is used by a tool called PHP_CodeSniffer (`phpcs`).
+Examples has a `phpcs.xml.dist` file at the root of the project. phpcs uses this
+file to specify the current coding standards 'sniffs' which code in the project
+must pass.
 
 Contributors should install `phpcs` in their local Drupal installation, and then
 use that to run `phpcs` against Examples as part of their development and review
-process.
+process. (See details below on how to install and run this tool.)
 
 Contributors can also patch the `phpcs.xml.dist` file itself, in order to fix
 the codebase to pass a given rule or sniff. Patches which do this should be
@@ -47,6 +47,10 @@ Like this:
     $ ../vendor/bin/phpcs -e --standard=Drupal
     // Shows you a bunch of Drupal-related sniffs.
 
+Note that there is an issue to require Coder and phpcs as part of Drupal core:
+https://www.drupal.org/node/2744463 Once this issue is fixed, you shouldn't need
+to install phpcs before using it.
+
 Running phpcs
 -------------
 

Diff for: TESTING.md

@@ -15,6 +15,12 @@ the testbot's behavior.
 You can find information on how to run `run-tests.sh` locally here:
 https://www.drupal.org/node/645286
 
+Examples is always targeted to the dev branch of Drupal core for the latest
+release. As of this writing, the latest release of Drupal core is 8.2.5, which
+means development for Examples should be against the Drupal 8.2.x development
+branch. When Drupal 8.3.0 is released, we'll start targeting Examples to 8.3.x,
+and so on.
+
 You should at least run `run-tests.sh` locally against all the changes in your
 patch before uploading it.
 
@@ -27,8 +33,68 @@ suggested workaround for this, since there is no best practice to demonstrate as
 an example. There is, however, this issue in core:
 https://www.drupal.org/node/2499239
 
+How To Run The Tests In The Drupal UI
+-------------------------------------
+
+Generally, you should run tests from the command line. This is generally easier
+than using Drupal's testing UI. However, here's how you can do it that way:
+
+Enable the Testing module.
+
+Visit the test list page at `admin/config/development/testing`.
+
+Since the tests are organized by module, you can search for a module name and
+get all the tests for that module. For instance, type in 'node_type_example' for
+all the tests related to that module.
+
+Click the check boxes next to the tests you want to run. If you find this
+tedious, it's time to learn to use the command line. :-)
+
+Click 'Run Tests.' You're now running the tests.
+
+Step-by-step: How To Run The Tests.
+-----------------------------------
+
+Begin with an installed Drupal codebase. Make a codebase, set up the database,
+etc. Note that you can use an existing Drupal instance but the best practice is
+to start fresh. Something not working right? Try a new installation.
+
+Use the dev branch of core for the latest release of Drupal. As of this writing,
+it's 8.2.x. When Drupal 8.3.0 is released, we'll target 8.3.x.
+
+Open the terminal window and move to the root directory of the Drupal
+installation:
+
+	$ cd path/to/drupal
+
+Put Examples into the `modules/` folder of the Drupal installation. If you are
+doing development on Examples, you should have already checked out the git
+repository into `modules/`, like this:
+
+	$ git clone --branch 8.x-1.x https://git.drupal.org/project/examples.git modules/examples
+
+Now you can run `run-tests.sh`, which, despite having a `.sh` suffix is not a
+shell script. It's a PHP script.
+
+You'll use the `--directory` option to have the test runner scan the Examples
+module directory for tests.
+
+Also, importantly, if your test site has its own URL, you'll need to supply that
+with the `--url` option. For instance, under MAMP, you must specify
+`--url http://localhost:8888/`.
+
+You can also use `--concurrency` to speed up the test run, and `--browser` to
+see detailed test results in a web browser instead of just text output in the
+terminal.
+
+	$ php ./core/scripts/run-tests.sh --browser --concurrency 10 --url http://localhost:8888/ --directory modules/examples
+
+This should run all the tests present in Examples. If you add a test and it
+doesn't appear in the list of tests to run, then you'll need to double-check
+that it's in the proper test namespace and that the class name (and thus the
+file name) ends in Test.
 
-What Tests Should An Example Project Have?
+What Tests Should An Example Module Have?
 ------------------------------------------
 
 Examples has a checklist for each module:

Diff for: events_example/events_example.info.yml

@@ -0,0 +1,7 @@
+name: Events example
+type: module
+description: Provides an example of subscribing to and dispatching events.
+package: Example modules
+core: 8.x
+dependencies:
+  - examples

Diff for: events_example/events_example.links.menu.yml

@@ -0,0 +1,4 @@
+events_example.description:
+  title: 'Events Example'
+  description: 'Example of dispatching and subscribing to events.'
+  route_name: events_example.description

Diff for: events_example/events_example.module

@@ -0,0 +1,75 @@
+<?php
+
+/**
+ * @file
+ * Demonstrates how to subscribe to and dispatch events.
+ */
+
+/**
+ * @defgroup events_example Example: Events
+ * @ingroup examples
+ * @{
+ * Demonstrates subscribing to, and dispatching, events.
+ *
+ * Events allow for different components of the system to interact and
+ * communicate with each other. Modules can either dispatch events, subscribe to
+ * events, or both.
+ *
+ * Subscribing to an event allows a module to declare that it would like to be
+ * notified anytime a specific event happens. A module can subscribe to any
+ * number of events, and can even subscribe to the same event more than once.
+ *
+ * Dispatching an event allows a module, or Drupal core subsystem, to notify any
+ * registered subscribers that a specific event has just taken place. When an
+ * event is dispatched the registered code for each subscriber is executed. For
+ * example, whenever a configuration entity is updated the Configuration API
+ * dispatches a new event allowing all subscribers to react to the change.
+ *
+ * This allows modules to extend other systems without the need to modify the
+ * original code.
+ *
+ * Each event has a unique string name. This string is often referred to as "the
+ * event", or "the event name". This string is how you identify which event(s)
+ * you are interested in. A complete list of events dispatched by core is
+ * available at
+ * https://api.drupal.org/api/drupal/core%21core.api.php/group/events/
+ *
+ * Drupal's event system is an extension of the
+ * @link http://symfony.com/doc/current/components/event_dispatcher.html Symfony
+ * EventDispatcher component @endlink, and implements the Mediator pattern.
+ *
+ * Subscribing to an event requires:
+ * - Defining a service in your module, tagged with 'event_subscriber'.
+ * - Defining a class for your subscriber service that implements
+ *   \Symfony\Component\EventDispatcher\EventSubscriberInterface
+ * - Using the getSubscribedEvents method to return a list of the events you
+ *   want to subscribe to, and which methods on the class should be called for
+ *   each one.
+ *
+ * For an example of subscribing to an event see the events_example.services.yml
+ * file. And the \Drupal\events_example\EventSubscriber\EventsExampleSubscriber
+ * class.
+ *
+ * Dispatching an event requires:
+ * - Defining a new static class with constants for unique event names and
+ *   documentation. Example: \Drupal\events_exampl\Event\IncidentEvents
+ * - Defining an event class that extends
+ *   \Symfony\Component\EventDispatcher\Event
+ *   Example: \Drupal\events_example\Event\IncidentReportEvent
+ * - Use the 'event_dispatcher' service in your code to dispatch an event and
+ *   provide an event object as an argument. Example:
+ *   \Drupal\events_example\Form\EventsExampleForm::submitForm()
+ *
+ * This example code is based off of the article @link
+ * https://drupalize.me/blog/201502/responding-events-drupal-8 Responding to
+ * Events in Drupal 8 @endlink.
+ *
+ * @see events
+ * @see \Symfony\Component\EventDispatcher\EventDispatcherInterface
+ * @see \Drupal\Component\EventDispatcher\ContainerAwareEventDispatcher
+ * @see service_tag
+ */
+
+/**
+ * @} End of "defgroup events_example".
+ */

Diff for: events_example/events_example.routing.yml

@@ -0,0 +1,8 @@
+# Define a route for our event dispatching example.
+events_example.description:
+  path: 'examples/events-example'
+  defaults:
+    _form: '\Drupal\events_example\Form\EventsExampleForm'
+    _title: 'Events Example'
+  requirements:
+    _permission: 'access content'

Diff for: events_example/events_example.services.yml

@@ -0,0 +1,16 @@
+# Subscribing to an event requires you to create a new service tagged with the
+# 'event_subscriber' tag. This tells the service container, and by proxy the
+# event dispatcher service, that the class registered here can be queried to get
+# a list of events that it would like to be notified about.
+#
+# For more on defining and tagging services see
+# https://api.drupal.org/api/drupal/core%21core.api.php/group/container/8.2.x
+services:
+  # Give your service a unique name, convention is to prefix service names with
+  # the name of the module that implements them.
+  events_example_subscriber:
+    # Point to the class that will contain your implementation of
+    # \Symfony\Component\EventDispatcher\EventSubscriberInterface
+    class: Drupal\events_example\EventSubscriber\EventsExampleSubscriber
+    tags:
+      - {name: event_subscriber}

Diff for: events_example/src/Event/IncidentEvents.php

@@ -0,0 +1,58 @@
+<?php
+
+namespace Drupal\events_example\Event;
+
+/**
+ * Defines events for the events_example module.
+ *
+ * It is best practice define the unique names for events as constants on a
+ * class. This provides a place for documentation of the events. As well as
+ * allowing the event dispatcher to use the constants instead of hard coding a
+ * string.
+ *
+ * In this example we're defining one new event:
+ * 'events_example.new_incident_report'. This event will be dispatched by the
+ * form controller \Drupal\events_example\Form\EventsExampleForm whenever a new
+ * incident is reported. If your application dispatches more than one event
+ * you can use a single class to document multiple events. Just add a new
+ * constant for each. Group related events together with a single class, define
+ * another class for unrelated events.
+ *
+ * The docblock for each event constant should contain an "@Event" tag. This is
+ * used to ensure documentation parsing tools can gather and list all events.
+ * For example,
+ * https://api.drupal.org/api/drupal/core%21core.api.php/group/events/
+ *
+ * The docblock should also contain a description of when, and
+ * under what conditions, the event is triggered. A module developer should be
+ * able to read this description in order to determine whether or not this is
+ * the event that they want to subscribe to.
+ *
+ * This class is declared as final so that it can not be extended. It should
+ * only ever be used to provide unique event names, and documentation.
+ *
+ * In core \Drupal\Core\Config\ConfigCrudEvent is a good example of defining and
+ * documenting new events.
+ *
+ * @see \Drupal\Core\Config\ConfigCrudEvent
+ *
+ * @ingroup events_example
+ */
+final class IncidentEvents {
+
+  /**
+   * Name of the event fired when a new incident is reported.
+   *
+   * This event allows modules to perform an action whenever a new incident is
+   * reported via the incident report form. The event listener method receives a
+   * \Drupal\events_example\Event\IncidentReportEvent instance.
+   *
+   * @Event
+   *
+   * @see \Drupal\events_example\Event\IncidentReportEvent
+   *
+   * @var string
+   */
+  const NEW_REPORT = 'events_example.new_incident_report';
+
+}

Diff for: events_example/src/Event/IncidentReportEvent.php

@@ -0,0 +1,69 @@
+<?php
+
+namespace Drupal\events_example\Event;
+
+use Symfony\Component\EventDispatcher\Event;
+
+/**
+ * Wraps a incident report event for event subscribers.
+ *
+ * Whenever there is additional contextual data that you want to provide to the
+ * event subscribers when dispatching an event you should create a new class
+ * that extends \Symfony\Component\EventDispatcher\Event.
+ *
+ * See \Drupal\Core\Config\ConfigCrudEvent for an example of this in core.
+ *
+ * @see \Drupal\Core\Config\ConfigCrudEvent
+ *
+ * @ingroup events_example
+ */
+class IncidentReportEvent extends Event {
+
+  /**
+   * Incident type.
+   *
+   * @var string
+   */
+  protected $type;
+
+  /**
+   * Detailed incident report.
+   *
+   * @var string
+   */
+  protected $report;
+
+  /**
+   * Constructs an incident report event object.
+   *
+   * @param string $type
+   *   The incident report type.
+   * @param string $report
+   *   A detailed description of the incident provided by the reporter.
+   */
+  public function __construct($type, $report) {
+    $this->type = $type;
+    $this->report = $report;
+  }
+
+  /**
+   * Get the incident type.
+   *
+   * @return string
+   *   The type of report.
+   */
+  public function getType() {
+    return $this->type;
+  }
+
+  /**
+   * Get the detailed incident report.
+   *
+   * @return string
+   *   The text of the report.
+   */
+  public function getReport() {
+    return $this->report;
+  }
+
+}