Announcing Greenhouse’s PHP Package

A couple weeks ago, I wrote a post about PHP’s Libcurl and its unfortunate interaction with Rails. The long story made short is this: Rails does not like the way that PHP sends multiple values on one parameter in form submissions. In that post, I suggested our users use Guzzle, which is a great library for interacting with APIs. While that suggestion still works, we can also offer a second option today.

Greenhouse is a great place to work and that is rarely more evident than when a problem like this presents itself. After diagnosing this problem, I suggested to our management team that this would be best solved by growing our own Greenhouse PHP package. It would hide implementation details from the user and could be written in such a way that both uses Guzzle and allow engineers to post to our applications endpoint in the most natural way. It didn’t lead to weeks of meetings, bureaucracy, and review to ultimately be killed; instead, this clear solution was encouraged. I was able to pause what I was working on and churn this package out, thus solving a problem for many of our current and future customers.

With that, I wrote Greenhouse Tools for our customers. The Greenhouse Tools package exists to help engineers more quickly set up their Greenhouse job board by providing a package of tools for retrieving items from the Greenhouse Job Board API.

The part of this package that addresses the multiselect bug is the Application Service. With the Greenhouse Application Service, I addressed the following three issues:

1. The Greenhouse application endpoint’s requirement that required fields be verified on the client-side. This package checks for the required flag in real-time and raises an error if any required fields are missing values.
2. Shield users from implementation details. Users should know $jobService->getJobs(); will always return a list of jobs, even if the implementation details have changed behind the scenes. We don’t want our users always needing new libraries, just one that will always work.
3. Allowing engineers to post applications to Greenhouse in a way as close to the most natural implementation of PHP’s libcurl.

The only difference in posting via the Greenhouse service and posting via Libcurl is in the submission of multiple values to a single parameter. While Libcurl would expect you to post the following:

<?php 
    $postVars = array( 
        'first_name' => 'Tommy', 
        'last_name' => 'Tester', 
        'email' => 'tommy.tester@example.com', 
        'resume' => new \CURLFile(
            '/path/to/resume.doc', 
            'application/msword', 'resume.doc'
        ), 
        'var[0]' => 'foo', 
        'var[1]' => 'bar', 
        'var[2]' => 'baz' 
    ); 
    curl_setopt($ch, CURLOPT_POSTFIELDS, $postVars);

The Greenhouse application service lets you do the following:

<?php 
    $postVars = array( 
        'first_name' => 'Tommy', 
        'last_name' => 'Tester', 
        'email' => 'tommy.tester@example.com', 
        'resume' => new \CURLFile(
            '/path/to/resume.doc', 
            'application/msword', 
            'resume.doc'
        ), 
        'var' => array('foo', 'bar', 'baz') 
    ); 
    $applicationService->postApplication($postVars);

That’s it! The Greenhouse Application Service will translate this to a valid Guzzle request, validate required fields are included, and POST the application while not requiring the engineer have any knowledge of Guzzle. If any errors are encountered in the process, we will throw a GreenhouseException which can be caught and handled on the customer end.

I was happy to be able to put this package together for our customers and to give Greenhouse a presence on Packagist. I hope engineers find this package useful and it helps them to implement Greenhouse quickly and effectively on their websites.

Originally published at tech.greenhouse.io on April 4, 2016.