Grayside.Org

Guzzle for Drupal: SDK Building

Grayside — Wed, 12 Dec 2012 05:42:44 +0000

For the last few months I’ve (intermittently) been thinking about how to build a nice PHP SDK for working with external APIs from PHP applications, and Drupal in general.

This post is a sort of round up of my thoughts, hopefully I’ll find time to complete this project so I can post a detailed followup.

Selecting Guzzle

I’ve come to the conclusion (as has Amazon) that Guzzle is the perfect HTTP Client framework to build such a thing in PHP. In the mean time, Drupal 8 has gotten fully onboard with the guzzled goodness. So it’s looking increasingly like a go-to library.

Decoupled architecture, careful obedience to the HTTP spec, lots of valuable (and optional) features, and a maintainer with a deep knowledge of cURL’s curlicues makes it a good system to lean on.

Basic Architecture

Guzzle has a very componentized architecture, and in recent months has separated out these components into separately downloadable packages, so you can use Composer to get just the pieces you need.

It also uses a Symphony-driven plugin architecture, which makes many different behaviors easily swappable. Check out the existing plugin library and realize that most of them are ridiculously easy to override with your own version of the plugin, either implementing the interface or extending what’s there.

Laying Out the Client

Have a single “Client” class namespaced to the API you want to integrate.
You can use the Service Definition DSL to quickly get something working, but I question the performance of doing so. I have some crazy ideas about coupling a discover service with a Guzzle Mimetype to created an automatic client testing harness.
You should probably have an abstract “Command” (API Resource) in place to impose any custom behaviors.
You should probably group “categories” of resources together using a lower level abstract class or interface to impose still more. For example, I want to add some fault tolerance by making certain “change” operations enqueue-for-retry on failure.

Add the Drupal

Using the Adapter interfaces, it took me about 20 minutes apiece to put together Drupal caching and logging plugins. These will be brought in place with the proper use statements in a Drupal-specific Client class I will create as an extension of the generic SDK client.

Similarly, I anticipate extending many of the Command classes with Drupal-specific variants to handle mapping (data conversion) from Drupal entities to the API payload structure.

Terms:

Drush Snippets: Menu Trace

Grayside — Sat, 11 Aug 2012 19:08:54 +0000

Random snippet of the day, find out what modules are involved in building out a given menu route definition. When you type a URI into your browser, Drupal’s menu routing system connects that to your page content by processing the path into instructions for how to build the page.

To use this script, copy the text or clone from github as a file, make it executable. It will automatically run with drush php-script. You can use --verbose for “full array notation” of each module’s change to the menu route. Or you can just use --pipe to get a list of modules and go look at the code directly.

In theory this should work with Drupal 7, but I haven’t gotten around to testing it yet.

Terms:

Extending Drush Commands

Grayside — Sat, 21 Apr 2012 07:21:54 +0000

The other day around the office, I was surprised to discover not everyone realizes that you can do some crazy stuff around extending drush commands.

First step: Read the documentation. Drush is intentionally written to be a command-line foil for Drupal, and if you’ve built a module, a few minutes digging into the well-done docs will go a long way. Check out the Drush API if you are of a mind, or for a more focused burst of hook goodness, get out your terminal and type:

$> drush topic docs-api

Once you have a grasp of the fine hooks you can use to piggy-back on and around any Drush command, you can take it to the next level.

Adding Options

Adding options to a Drush command allows you to create more sophisticated, controllable extensions to core command behaviors.

There are several ways of doing this.

The command allows this already

Let’s not make this too complicated. Commands are sometimes intended as passthru mechanisms, such as drush rsync. How does it accept any rsynch command? It has a command definition that includes allow-additional-options => TRUE.

The user operates in non-strict mode

If the developer can set a flag, so can the user! You might have already seen this warning:

Unknown option: --simple.  See `drush help help` for available options. To suppress this error, add the option --strict=0.

This means that any time the user adds --strict=0 to a drush command invocation (or to their drushrc file for that specific command), your drush code can use drush_get_option() to access the submitted value.

But for the clever command extension…

You’ll want to implement hook_drush_help_alter(). Using this hook, you can add new options to a drush command that will be be qualified as “strict”, and will even show up in the help entry for the command in the user’s system.

Why didn’t you show source code?

Well, I had this small idea in mind, but it evolved rather quickly into a legitimate project. Go check out Drush Notify. It’s pretty Ubuntu-specific out the gate, but it serves as a great example of a powerful drush “extension” that defines no commands.

Terms:

drupal

drush

Release: Organic Groups 6.x-2.3

Grayside — Wed, 28 Mar 2012 21:27:05 +0000

Today was the release of OG 6, Version 2.3

We have a fine assortment of changes (see the changelog), ranging across:

Extensive og.module commenting.
Views integration improvements.
Many “OG, what are you thinking?” bugfixes.
And even some performance enhancements.

This release covers three classes of issues:

The remaining low hanging fruit languishing in the issue queue over the last two years.
Lowish-hanging fruit that I had the time to finish myself.
Development of enhancements and bugfixes I ran into during the work hours.

As I presented last time, I have a bit of a manifesto on how I’m approaching changes to OG6. Unusual levels of conservatism have led to such oddities in a Drupal project as a function with a @deprecated tag.

There are still items in progress in the issue queue, but since most everyone has moved on to the fantastic Drupal 7 version of Organic Groups, there are very few people contributing their efforts. That’s fine, but you can start to expect most changes to OG6 to come by way of my own itches. I don’t use Notifications, I don’t use multi-group posting, I don’t use the audience widget. If you care about these things, please help the many people that share your plight and present some patches and reviews in the queue.

Terms:

drupal6

organic groups

Features Module, Then, Now, and in the Future

Grayside — Wed, 28 Mar 2012 21:03:03 +0000

Between the issues queue, Twitter, podcasts, and ad hoc discussions, there is a lot of confusion about what the Features module is all about. As someone that has used and developed in it for a long time, I thought I’d lend my perspective. My sense is the maintainers are on the same page, but don’t hold them to this post.

Then

Features is a module to help site builders and command-line gurus easily package up the configuration associated with a specific use case (like a blog), and manage it in code.

Unfortunately, there is no standard for doing this, so Features develops a mechanism for wrangling exports. This is sad, because it confuses the use case of the Features module itself.

Now

Unless you are active in the Distributions movement or style of site-building, the sense I get is that this is a common thought process for those that run across Features:

I need to toss my configuration into code so I can ship my website around. This Features module things has traction. Darn, the UI sucks, I have to click all these little boxes. And all these info hooks, info alter hooks, and caching layers complicate my day.

Meanwhile, in #drupal-features, a paraphrase:

We totally need to get the exporting out of Features. It adds complexity and attracts all these irrelevant use cases to the issue queue.

Future

The Configuration Management Initiative is exciting. From the perspective of a Features user and developer, it finally defines the standard and mechanism for configuration. That means Features finally has a target for how to pull the out-of-scope pieces out.

After several conversations at DrupalCon, I’m expecting we’ll be seeing a 2.x architectural branch for Features that drops the export stuff. That doesn’t mean it will become an inconsequential module–it turns out capturing use cases in configuration is surprisingly complex. People do not agree on what bits and pieces naturally fall together. But that’s okay, because we are reviving the Kit specification. Expect more from me on that in the future, I think standards like that are key to keeping Drupal intuitive as the Distributions-driven approach to Drupal continues to accelerate.

Terms:

features

drupal

cmi

Release: Organic Groups 6.x-2.2

Grayside — Fri, 13 Jan 2012 19:16:45 +0000

I have just tagged the first OG6 release since March of 2010.

We have a fine assortment of changes (see the changelog), ranging across:

New Hook API Documentation
Views integration improvements
Localization improvements
Miscellaneous areas of moderate interest

This release locks in some changes, clarifies the status of Notifications (sticking with the 2.x line for now), and sets up OG6 for a stable position to start looking at what should happen next. I’ve posted a sort of maintainer’s philosophy position on how I see OG6 moving forward, you can read it at the d.g.o address of Organic Groups. What does all that translate into for my next steps?

Well, aside from a few clear cases, it’s still very much up to the community. I’m going to focus on a few good patches, and see if I can help the groups.drupal.org-related issues, performance, and the Weirdness subqueues. I’m hoping to have enough cool stuff pulled together to release 2.3 in honor of Drupalcon Denver.

Terms:

drupal6

organic groups

Infinite Null: Sorting NULL to Last

Grayside — Thu, 25 Aug 2011 04:01:43 +0000

Please, keep in mind this post was written for Drupal 6 and Views 2! D7/Views 3 sites might not take so kindly to it.

Recently I was looking at creating a new Todo Feature with a due date. I cracked open CCK’s manage fields UI and added a date field, careful to keep in mind that the default value should be no date, which just happens to translate as NULL. You see, for my Todo use case, not all Todos would have a deadline.

My next step was to create a View of all upcoming items. I wanted the next most urgent todo to float to the top of the list. Sadly, NULL counts as 0 in database land, so my carefully clicked Sort was preloading all my urgent todos with all the lowest priority tasks.

Seeing as this was a SQL problem, I googled the ‘net for viable query tweaks. I found a nice article illustrating exactly what I wanted: MySQL Sort Order with NULL. The grand secret? Sort first by whether the duedate is NULL to flip your empty values to the bottom of the result set.

The fastest way for me to apply this tweak to my feature was to hack the Views query. hook_views_query_alter() is usually a horrible decision. Once you’ve put it into code, tweaking your View a lot around your alteration can quickly result in a broken query. Meanwhile:

/**
 * Implementation of hook_views_query_alter().
 */
function example_views_query_alter(&$view, &$query) {
  if ($view->name == 'example_listing') {
    array_unshift($query->orderby, 'ISNULL(node_data_field_duedate_field_duedate_value) ASC');
  }
}

(For a longer use case on this Views bandaid, see Correcting views queries using views_query_alter)

I arrived here by turning on the Devel module, and dropping a dpm($query) into that function first thing. This gave me the array structure of my View, including the various SQL entries for the ORDER BY arguments. A quick and dirty array_unshift() forces the NULL check for my date field (the alias I also found in the $query object, there are more elegant methods) onto the top of the ordering hierarchy.

Bingo! NULL-dated nodes are sorted to last.

Terms:

Configure Drush in Your Git Repository

Grayside — Sat, 20 Aug 2011 06:53:18 +0000

One of the neat features of Drush is it’s configurability. Setting the defaults for various behaviors and command options allows you to build really simplified, specialized workflows. You can create personal settings defaults by dropping a `drushrc.php` file in one of the places Drush will look, such as inside a .drush folder of your home directory.

It turns out this little capability has provided some very simple wins for developers at GoingOn. We pass around our projects and sites as a subdirectory of a Git repository that contains various things, such as documentation, deployment tools, and drush commands. Unfortunately, this slightly irregular practice disconnects Drush from the Drupal site and excludes those drush commands from the standard directories drush scans.

We fix this by making Drush aware of the Git Repo. There is a command-line script you can use to check if you are anywhere in a Git repository. By configuring Drush to check for a Git Repo on every drush bootstrapping, we give Drush a chance to pick up a bonus, repository-specific Drush config file.

Add this snippet to your drushrc.php file:

$output = array();
exec('git rev-parse --show-toplevel 2> /dev/null', $output);
 
if (!empty($output)) {
  $repo = $output[0];
 
  $options['config'] = $repo . '/drush/drushrc.php';
  $options['include'] = $repo . '/drush/commands';
  $options['alias-path'] = $repo . '/drush/aliases';
}

This script checks the current directory for participation in a git repository. If there is one, it looks at the root of the git repository for a ‘.drushrc.php’ file to provide repo-specific instructions to Drush. We use this to configure paths to external resources that can vary by code version, as well as setting the Drupal site root for the Drupal site sihpped with that particular repository.

The last line also seeks out a `scripts/` directory in the repository root, which it will scan recursively for any files ending in `.drush.inc`. This allows us to ship versioned drush commands with each repo instead of documenting a complex individual installation process.

There are many other things you can do with a little poking about in the options for a drushrc file, to learn more start with the drushrc.php example.

Update 7/16/2012: Updated code example to the same provided in Drush docs. You can now leverage this trick outside the root directory of your code repository. Also removed not applicable git context resulting in invalid configuration paths.

Terms:

drupal

drush

git

D7 Upgrade Process: Backports to Close the Gap

Grayside — Wed, 17 Aug 2011 05:40:01 +0000

The following post originally appeared on the GoingOn.com blog.

After more than a year of continuous investment in GoingOn’s Drupal 6 platform, the idea of upgrading to Drupal 7 is incredibly daunting. We have custom modules from form behaviors down to the access layer, we have features encapsulating hundreds of exported components, and an aggressive feature release schedule that does not set aside 6 months for a complete rewrite of the codebase just for a new version of Drupal. What to do?

We’ve been playing around with the idea of iterating our Drupal 6 platform toward Drupal 7. By pulling markup, design patterns, APIs, and architecture in Drupal 7 down into platform incrementally, we hope to shorten the final leap that will come when upgrading the entire system.

Driving Current Drupal Version Closer to Expected Drupal Version

^{Usability metaphors in site architecture and development practices sometimes works.}

The extra work involved might well take more aggregate time to develop, but that time will be amortized across small, manageable pieces that can be more intelligently inserted into the development schedule.

Here are the backport opportunities we’ve identified:

Design Patterns

Vertical Tabs, Contextual Links, Toolbar, Elements, Contact

Many of the design patterns in Drupal 7 are available through a combination of backport modules and creative theming. The Toolbar module doesn’t have a backport, but peeking into the repository for the Admin Menu I spy something that makes it look like D7’s Toolbar.

By pulling these patterns from D7, we gain two benefits:

We can build out the rest of our user interface around D7 design assumptions, instead of D6 assumptions. This will save effort in a theme redesign and upgrade.

We can trickle D7 designs in front of our users, allowing them to adjust to a few changes ahead of time instead of waking up one morning to find a completely rearranged website.

Our use of Vertical Tabs liberally around node forms is not cutting edge, but has allowed us to package complex forms with a Drupal 7 pattern, instead of resorting to harder-to-maintain multi-step forms.

System Plumbing*

Drupal Queue, Admin Role, Password, File, Mail System, Simpletest

The flow of code that goes on under the hood has a few interface points where it is relatively easy to grab a D6 backport and make your modules look just a little more like Drupal 7 code.

Judging by an IRC chat I just overheard the files[] mechanism might be dropped for something simpler in one of the next few point releases.

I hadn’t realized until writing this that URL Alter was cooked into core. The ability to ignore the special rules around around custom_url_rewrite_inbound() and go straight for hook_url_inbound_alter() is great. It also makes our custom code using it D7 ready.

* For purposes of this post, plumbing refers to the flow of code and data between its storage and the rendering process. Pretty broad category.

Database & Performance

Pressflow, DBTNG, Cache Backport

You can get a lot closer to Drupal 7 performance behaviors simply by using Pressflow, which has held backports from and experiments for Drupal 7 for years.

Most members of the Drupal community are already well aware that if performance is important for your project, grabbing Pressflow is an easy and non-threatening win. By using it for D6, you will be coding against session handling that is closer to D7’s, as well as being able to make use of other performance enhancing systems, such as serving images via Varnish as an ongoing improvement across your upgrade process.

Contrib Backports

This is a category of another sort. Usually when you think about Contrib modules for D7, you are looking for the upgraded version of the modules you are already using. However, what if there is a D7 module you want to use, or at least, could use? The D6 version of that module has just become a backport to facilitate your upgrade path.

This is a good solution to deal with unmaintained modules that have since been eclipsed by more energetic projects, as well as custom code you don’t really want to see again. We’re pretty excited to start playing with the Boxes module for this reason.

I’m going to skip listing competing modules in which one has an upgrade path and not the other. The Similar Module Review group might have information that will help you find competing modules that may just be a cleaner path forward.

Thanks to Lullabot’s Friday Roundup (June 24th) for pointing out backports of Password, Contact, and File. Thanks to David Reid for creating and maintaining what seems like most of these modules.

So, did this work? We are still putting together the details of this plan. A followup post in a few months will report on how it goes. If you have thoughts about this approach to the upgrade, additional worthwhile backports, or alternate ideas on how to make the time for an upgrade, please post a comment!

Terms:

How to Override a Views Field Template from a Module

Grayside — Wed, 15 Sep 2010 21:07:05 +0000

Some months ago I wanted the solution to overriding a Views Field template entirely from within a module. I spent hours trawling documentation and issues, and playing with a little trial and error. In the end, I came up with a solution:

/**
 * Implementation of hook_theme().
 */
function custom_module_theme($existing) {
  return array(
    'views_view_field__view_name__field_name' => array(
      'arguments' => array('view' => NULL, 'field' => NULL, 'row' => NULL),
      'template' => 'views-view-field--view-name--field-name',
      'original hook' => 'views_view_field',
      'path' => drupal_get_path('module', 'custom_module') . '/theme',
    ),
  );
}

By defining a Views template in this way, you are doing the equivalent to building your template and dropping it into your Theme’s directory. This is sufficient for Views to notice the existence of the template from within your module. At that point the standard Views logic of finding the most specific template available for each field comes into play. In this case, every instance of field name in view name will use this template… unless, of course, I have a more specific template somewhere that targets that field in a specific display.

Note that the theme key and template name are the same, but for the swapping of hyphens and underscores. The way both of those are named is critical, else Views will not properly notice the template. All the options listed in Theme Information in the Views UI is available for use here.

Note that this is very derivative of the hard work of others, and I will link to it here when I come across it again.

views template overrides in module directory was one of my key references. Since I checked that thread, the marvelous @dereine posted a patch with the intent to guide Views to find theme templates in module directories as well. It Needs Review, so if the code above bores you, go review the patch!

Terms:

drupal

views

theming