
    ____              __                  __   ___    ____  ____
   / __ )__  ______ _/ /_  ___  _________/ /  /   |  / __ \/  _/
  / __  / / / / __ `/ __ \/ _ \/ ___/ __  /  / /| | / /_/ // /  
 / /_/ / /_/ / /_/ / / / /  __/ /  / /_/ /  / ___ |/ ____// /   
/_____/\__,_/\__, /_/ /_/\___/_/   \__,_/  /_/  |_/_/   /___/   
            /____/                                              


README

Drupal integration for BugHerd.

BugHerd turns client feedback into actionable tasks.

Your clients report issues by making annotations right from the site being worked on.

BugHerd turns these into full bug reports with all the info you need to fix the problem.

For more info visit the official BugHerd website on www.bugherd.com

-- GETTING STARTED --

1. Install Bugherd API in the usual way
   (https://www.drupal.org/node/1897420)
3. Go to Administration > Configuration > System > BugHerd
   (/admin/config/system/bugherd)
4. Enter the BugHerd project key found on Bugherd.com for the project under the install Bugherd option
5. Optionally disable BugHerd for admin pages
6. Click "Save configuration"

Bring on the bugs!

-- USING THE REST API FROM PHP --

The module ships a client service for the BugHerd REST API (v2), so other
modules can read and create BugHerd data from PHP.

1. Get your personal API key from BugHerd under Settings > General Settings.
2. Enter it under "REST API" on the BugHerd configuration form, or better,
   keep it out of exported configuration by adding this to settings.php:

     $config['bugherdapi.settings']['api_key'] = 'your-api-key';

Then use the bugherdapi.client service:

  $client = \Drupal::service('bugherdapi.client');

  // Or, preferably, inject Drupal\bugherdapi\Client\BugherdClient.
  $projects = $client->getProjects(TRUE);
  $tasks = $client->getTasks($project_id, ['status' => 'backlog']);
  $task = $client->createTask($project_id, [
    'description' => 'The contact form throws a 500.',
    'requester_email' => 'client@example.com',
    'priority' => 'critical',
  ]);
  $client->createComment($project_id, $task['id'], 'Fixed in the latest deploy.');

Available methods: getOrganization(), getUsers(), getMembers(), getGuests(),
getProjects(), getProject(), createProject(), updateProject(),
deleteProject(), getTasks(), getTask(), createTask(), updateTask(),
getComments(), createComment(), getWebhooks(), createWebhook() and
deleteWebhook(). Listing methods page through all results for you.

Every method throws Drupal\bugherdapi\Exception\BugherdApiException when the
request fails, so wrap calls in a try/catch:

  try {
    $tasks = $client->getTasks($project_id);
  }
  catch (\Drupal\bugherdapi\Exception\BugherdApiException $e) {
    if ($e->isRateLimitError()) {
      // BugHerd allows about 60 requests per minute.
    }
  }

Use $client->hasApiKey() to check whether a key is configured before calling.

-- MAINTAINERS --

Fons Vandamme - https://www.drupal.org/u/fons-vandamme
