Things to Consider When Writing a Drupal Integration

One of the many things Drupal excels at is integrating with other services. Some popular integrations are made even easier by the existence of contributed Drupal modules (such as the one for Google Analytics). But, many times, there isn't a ready-built solution, or the one that's available doesn't quite suit your needs. At Ashday, we've built many integrations between Drupal and other systems, and although every integration is different, there are some things we've learned that are good to consider when writing most any integration.

Do You Need to Build Something New?

Even if there is an existing Drupal module for the integration that you need, it's important to determine if you actually want to use it. Sometimes, integration modules are written for certain use cases, which may not line up with exactly what you need the integration to do, and could in fact make things more complicated for you than not using a pre-existing module at all.

For instance, when we created a Solr integration, we had to evaluate whether to use the existing Search API Solr module or write our own integration, and in the end, we decided to write our own. Why? Because when we were evaluating our options, we found that the module wasn't designed to index the content of our site in the particular way we needed it to, and it also didn't quite properly support the "More Like This"-style search which Solr itself is capable of. Because of this, we only had a few options.

• We could modify our site to fit the capabilities of the module, but most of the time, as in our case, that isn't really an option.
• We could use the module and try to adapt it to our needs. This would mean not only installing the module and figuring out how to use it, but also digging into how it was written in order to make changes to it. With some modules, such as Search API Solr, this can be a pretty big task. It's a large, complicated module, and figuring out where and how to make the necessary changes can be a challenge… and that's assuming that the module is structured in such a way that the changes are easy to make.
• We could write an entirely custom integration.

We wound up going with the third option. "But wait," you might wonder, "If the existing module is so complicated, wouldn't writing your own integration mean needing to create all of that same stuff yourself?"

And the answer to that is no. Whereas a Drupal contrib module usually has to be designed in a rather generic way, so that it can suit as many people's disparate needs as it possibly can, an entirely custom-coded integration can focus solely on the functionality that is needed for your particular use case. Just because the system you're integrating with supports something, doesn't mean you necessarily have to. With the Solr integration in particular, building exactly what we needed as a custom integration wound up being much faster and more maintainable than it probably would have been to take the existing module and modify it to suit our needs.

How Much Drupal Should You Use?

Depending on what sort of integration you're writing, one thing to consider is how much it should rely on Drupal. Drupal includes numerous powerful tools, such as its service architecture and Form API, which can be leveraged to make your integration more flexible, and even save time in the process. At the same time, tying your integration to Drupal makes it less portable. For instance, if you were creating an integration which would display content from a remote system on several different websites, and only some of those sites actually use Drupal, then it may be worth creating the integration mostly using regular ol' PHP. By creating the integration as a set of classes or functions that don't depend on Drupal, each site can then use those same functions, and add just the few things that are needed to make them work well on that site; for instance, a Drupal site may need routes and permissions set up "the Drupal way" separate from the reusable part of the integration.

Creating a more generic integration in this way can also make it more compatible between different versions of Drupal. If your main integration doesn't rely on Drupal, it will work on Drupal 7, 8, 9, and even more, with only the minimal code to make it actually work on each site needing to be changed between them.

Another example: Say you're integrating with an analytics tool. You could either create a complex configuration form that fits into the Drupal administration interface and uses Drupal's form API, config system, and permissions, or you could just hardcode the specific settings you need somewhere in your codebase. The former way is the more "Drupal" way of doing it and is more configurable (this is the approach taken by the Google Analytics module), but the latter method can be very fast to code, and if you only rarely need to change anything about your configuration, it can be a great time savings over creating a complex Drupal-specific integration module.

Can This Be Contributed?

If your integration ultimately does make use of Drupal's helpful built-in features, great! Now it's time to ask "Can I contribute this module so that other other people can use it on their own Drupal sites?" If you are integrating with some tool or remote system that other people might also want to integrate with in a similar fashion, then the answer should probably be yes.

Contributing your custom integration module to Drupal.org can have a number of benefits—not the least of which is that it is an excellent way to give back to the Drupal community as a way to say "thank you" for all they've done to make Drupal possible. But there's another benefit as well: If you contribute a custom integration module, that means that other developers may start using it, looking at the code, and making improvements to it. Maybe your integration is fairly small, and only accounts for the handful of use cases that you need. The next person who uses the module thinks that something could be added or changed to improve the module. Suddenly, you have other people making suggestions or even writing code for you, which you can then benefit from by including such changes in the integration you're already using.

This is what we did with our HelloSign module for creating eSignature requests; we built it for one site which needed such functionality, then we contributed it. Once we did so, other developers started looking at the module and helping us to make all sorts of improvements to the module, and some even submitted patches to help improve the module. We also got free t-shirts out of it, so hey, who knows what might happen when you contribute!

Conclusion

There are many things to think about when you're building a Drupal integration, and although I've only written about three of them today, I think they are the guiding questions which help to determine how your integration is built. If you can answer all three of these questions before getting too far into writing your integration, you're much more likely to end up with a system in place that will serve you well long-term, even if the exact requirements for the integration eventually changes—which, in my experience, they almost certainly well.