Spinning Code

I recently completed a Drupal 8 project that required pulling data from a remote database.  The actual data is not terribly complicated, so Drupal’s role in this case is mostly to provide an abstraction layer that converts the database into a (cacheable) JSON response. Pulling all the pieces together took a little more research and guessing than I expected so I figured I might save a few people time by writing it up. This is more of an intermediate than a beginner project and so I’m going to skip over lots of detail that important to making it all really work. To really understand what’s happening here you’ll want a basic understanding of Drupal 8’s controllers and database services.

What we’re doing here is creating a database service and a controller to provide a JSON endpoint. We’ll define the database connection, the Drupal service, and then the controller.

Drupal allows us to define database connections in the main settings file. This allows easy access to Drupal’s database services and query classes.

Connection Definition

The first step is to define the database connection in settings.php:

<?php
$databases['remote']['default'] = [
  'database' => 'extra_data',
  'username' => 'accessingUser',
  'password' => 'UseGoodPasswordsIn2017&Beyond',
  'prefix' => '',
  'host' => '10.10.1.1',
  'port' => '',
  'namespace' => 'Drupal\\Core\\Database\\Driver\\mysql',
  'driver' => 'mysql',
  // I'll explain this detail later.
  'pdo' => [
    \PDO::ATTR_TIMEOUT => 5,
  ],
];

Services

Next we need to create a new database service using the new connection information. Drupal core’s database service can be leveraged to connect to additional databases by just defining your new connection as a service in your module’s services.yml file.

services:
  mydataservice.database:
    class: Drupal\Core\Database\Connection
    factory: 'Drupal\Core\Database\Database::getConnection'
    arguments: ['default', 'remote']

Notice the arguments from the database service are the array keys (in reverse order) from the settings.php definition of the connection.

That’s all it takes to create a new service that wraps around your database.

The Controller

That service is all well and good as far as it goes, but if we want to actually to send the data to the browser we need a controller to leverage our new service and send the response.

Using dependency injection I attached the service to the controller and it looked like it worked great.

<?php
  /**
 * Constructs a new DataSearchController object.
 */
public function __construct(ConfigFactory $config_factory, Connection $dataservice) {
  $this->config = $config_factory->get('mydataservice.datasettings');
  $this->database = $dataservice;
}

/**
 * {@inheritdoc}
 */
public static function create(ContainerInterface $container) {
  return new static(
    $container->get('mydataservice.database')
  );
}

public function getData(Request $request) {
  $query = $this->database->select('mytable', 'mt');
  // From here you gather your data and send your response...
}

In fact it did work flawlessly all the way through initial testing. Using the database service to get the data and the cacheable JSON response technique I’d worked out previously everything came together quickly. You could make a request of the controller with your search terms and the browser gets back a list of objects for display.

Then just before launch the client physically relocated the database server and didn’t tell us it would be offline. Turns out we hadn’t tested what happens to an injected database service when there is no response from the remote database server. The request would wait for the database connection to time out and then throw an exception that didn’t get handled in my code at all. There was no place to add a nice error message and it was incredibly slow since the timeout was 30 seconds.

So at the last minute I had two more problems to solve: trap the error and shorten the timeout on PDO connections.

Drupal 8 database services attempt their connection when the service itself created. It you use dependency injection that means exceptions need to be caught in create(). But create() cannot send a response to the browser, that has to happen later when the function that corresponds to the active route is called by the kernel.

My solution was to make the database service an optional parameter on the controller, and adjust the static returned by create based on the exception thrown:

<?php
  /**
 * Constructs a new DataSearchController object.
 */
public function __construct(ConfigFactory $config_factory, Connection $dataservice = null) {
  $this->config = $config_factory->get('mydataservice.datasettings');
  $this->database = $dataservice;
}

/**
 * {@inheritdoc}
 */
public static function create(ContainerInterface $container) {
    try {
      return new static(
        $container->get('config.factory'),
        $container->get('mydataservice.database')
      );
    }
    catch (\Exception $e) {
      return new static(
        $container->get('config.factory')
      );
    }

  public function getData(Request $request) {

    if (!$this->database) {
      throw new HttpException(404, $this->config->get('database_offline_message'));
    }
    $query = $this->database->select('mytable', 'mt');
    // From here you gather your data and send your response... 
  }
}

The other way to handle the exception would be to load the connection from Drupal’s service container when you need it in place of using dependency injection for that service.

Also, notice we’re throwing a 404 error. Ideally it would return a 5xx type error, but those trigger other behaviors that prevented me from providing nice errors for the JavaScript application to process easily. Our controller also had a page display (to send the JavaScript libraries and base markup for the actual interface on application startup), which meant that we needed to create a reasonably well themed response in that function as well:

<?php
    // If the database is offline, then send error message.
    if (!$this->database) {
      \Drupal::service('page_cache_kill_switch')->trigger();
      $message = $this->config->get('database_offline_message');

      $error = [
        '#theme' => 'dataservice_error_page',
        '#attributes' => [
          'class' => ['dataservice', 'database-offline'],
          'id' => 'dataservice-error',
        ],
        '#message' => [
          '#type' => 'processed_text',
          '#text' => $message['value'],
          '#format' => $message['format'],
          '#filter_types_to_skip' => [],
        ],
        '#title' => $this->t('Database Offline'),
      ];

      return $error;
    }

Settings revisited

So that fixed the errors, but still meant we had a really long wait for the database connection to time out before the connection error is even thrown in the first place. And now we come back to that PDO section of the database connection definition.

<?php
$databases['remote']['default'] = [
  'database' => 'extra_data',
  'username' => 'accessingUser',
  'password' => 'UseGoodPasswordsIn2017&Beyond',
  'prefix' => '',
  'host' => '255.255.255.255',
  'port' => '',
  'namespace' => 'Drupal\\Core\\Database\\Driver\\mysql',
  'driver' => 'mysql',
  // Now is when I explain this
  'pdo' => [
    \PDO::ATTR_TIMEOUT => 5,
  ],
];

PDO expects you to override settings at connection time not in a settings file. So I couldn’t just update my PHP.ini and call it a day but I also couldn’t find any documentation on how to change any PDO settings. Leveraging the power of open source I started to follow the code paths, actually reading through how Drupal establishes MySQL connections and, found I it.

If you add a subarray in your connection definition keyed to ‘pdo’ Drupal will load and apply those settings instead of the defaults. There are a couple settings that Drupal insists on being right about for performance, stability, and security reasons, but timeout and many others are fair game.

Awhile back I wrote up a pattern for creating static blocks on Drupal 8 sites. This week I was working on a site where one of those blocks needs to be enabled or disabled on specific nodes at the discretion of the content author. To make this happen, I’m adding a new feature to my pattern.

In older versions of Drupal there were a number of ways to go, like the PHP Filter, or custom handling in the block’s view hook, but I figured there were probably more appropriate tools for this in Drupal 8.  And I found what I needed in the Condition Plugin (more evidence that plugins are addictive). According to the change record they were designed to centralize a lot of the common logic used for controlling blocks, and I found it works quite nicely in this case as well (although a more generalized version might be useful).

I have the complete condition plugin at the end so you don’t have to get all the details exactly right as we go.

I started by adding a boolean field to the content type named field_enable_sidebar. Then I using drupal console generated the stub condition plugin:drupal generate:plugin:condition. In doing this the first time I also looked at the one defined in the core Node module to handle block visibility by content type.

The console will ask you a couple questions, obviously you can attach it to any module you’d like and call it whatever you’d like. For this example I have it in a fake module called my_blocks and the condition is named SidebarCondition. But the next couple questions are less obvious and more important.

The context type should be set to entity since we are looking to work based on the node being displayed.

Next it’s trying to filter between entity types, and since we’re doing this based on the node content entity type, select “Content” to get a list of content entities on your site.

Finally select “Content” again since that’s the label for node entities in Drupal 8. If you have your field on another content entity type (like a taxonomy term, or a file), pick that entity here instead and rest of this should still work with minor editing.

Once you run through the wizard you’ll have a new file in your module: my_blocks/src/Plugin/Condition/sidebarContition.php

The condition plugin contains two main elements: a form that’s attached to all block settings forms, and an evaluate function that is called by blocks to determine if this condition applies in their current context.

buildConfigurationForm() defines the form array elements you need. In this case that means a simple checkbox to indicate that this condition applies to this block. We also need to define submitConfiguration() to save the values on block save.

  public function buildConfigurationForm(array $form, FormStateInterface $form_state) {
    $form['sidebarActive'] = [
      '#type'          => 'checkbox',
      '#title'         => $this->t('When Sidebar Field Active'),
      '#default_value' => $this->configuration['sidebarActive'],
      '#description'   => $this->t('Enable this block when the sidebar field on the node is active.'),
    ];
    return parent::buildConfigurationForm($form, $form_state);
  }

  public function submitConfigurationForm(array &$form, FormStateInterface $form_state) {
    $this->configuration['sidebarActive'] = $form_state->getValue('sidebarActive');
    parent::submitConfigurationForm($form, $form_state);
  }

In the complete example you’ll see there is summary() which provides the human friendly description of the values that have been set for this condition.

Now let’s jump back to the top of the plugin and review the annotation. Conditions are annotated plugins and those questions I guided you through above were used to generate the annotation at the start of the file:

/**
 * Provides the 'Sidebar condition' condition.
 *
 * @Condition(
 *   id = "sidebar_condition",
 *   label = @Translation("Sidebar block condition"),
 *   context = {
 *     "node" = @ContextDefinition(
 *        "entity:node",
 *        required = TRUE ,
 *        label = @Translation("node")
 *     )
 *   }
 * )
 */

This is defining the context you’ll want passed to the condition for evaluation. In this case we are requiring that a node entity labeled “node” is provided when we need it.

The real work of the plugin is handled by evaluate():

  /**
   * Evaluates the condition and returns TRUE or FALSE accordingly.
   *
   * @return bool
   *   TRUE if the condition has been met, FALSE otherwise.
   */
  public function evaluate() {
    if (empty($this->configuration['sidebarActive']) && !$this->isNegated()) {
      return TRUE;
    }
    $node = $this->getContextValue('node');
    if ($node->hasField('field_enable_sidebar') && $node->field_enable_sidebar->value) {
      return TRUE;
    }
    return FALSE;
  }

The first conditional ensures that this plugin doesn’t disable all blocks that aren’t using it. Next we ask for the context node value we defined in the annotation, which provides us the current node able to be displayed. Since not all node types are guaranteed to have our sidebar field we first check that it exists and then check its value and return the correct status for block display.

Now every time a user checks a box on the node, any blocks with this condition enabled will be displayed along with the node. And the best part is that the user doesn’t need to even have block display permissions, we’ve allowed them to bypass that part of the system entirely.