Species.php

<?php

namespace ResTelae\Gbif;

/**
 * GBIF: species.
 */
class Species extends Gbif {

  /**
   * Lookup details for specific names in all taxonomies in GBIF.
   *
   * Usage:
   * @code
   *   use ResTelae\Gbif\Species;
   *
   *   $species = new Species();
   *
   *   // All data for species #1;
   *   $species->nameUsage([], 'all', 1]);
   *
   *   // Name usage for a taxonomic name.
   *   $species->nameUsage(['name' => 'Puma', rank' => 'GENUS'])
   *
   *   // All name usages.
   *   $species->nameUsage();
   *
   *   // References for a name usage.
   *   $species->nameUsage([], 'references', 2435099);
   *
   *   // Species profiles, descriptions.
   *   $species->nameUsage([], 'speciesProfiles', 3119195);
   *   $species->nameUsage([], 'descriptions', 3119195);
   *   $species->nameUsage([], 'children', 2435099);
   *
   *   // Vernacular names for a name usage.
   *   $species->nameUsage([], 'vernacularNames', 3119195);
   *
   *   // Limit number of results returned.
   *   $species->nameUsage(['limit' => 3], 'vernacularNames', 3119195);
   *
   *   // Search for names by dataset with datasetKey parameter.
   *   $species->nameUsage('[
   *     datasetKey' => 'd7dddbf4-2cf0-4f39-9b2a-bb099caae36c',
   *   ]);
   *
   *   // Search for a particular language.
   *   $species->nameUsage(['language' => 'FRENCH'], 'vernacularNames', 3119195);
   * @endcode
   *
   * @param array $args
   *   An associative array, with the following elements:
   *   - 'name' (string): filters by a case insensitive, canonical namestring,
   *     e.g. 'Puma concolor'.
   *   - 'language' (string): language, default is English.
   *   - 'datasetKey' (string): filters by the dataset's key (a uuid).
   *   - 'sourceId' (integer): filters by the source identifier.
   *   - 'rank' (string): taxonomic rank. Filters by taxonomic rank as one of:
   *     'CLASS', 'CULTIVAR', 'CULTIVAR_GROUP', 'DOMAIN', 'FAMILY', 'FORM',
   *     'GENUS', 'INFORMAL', 'INFRAGENERIC_NAME', 'INFRAORDER',
   *     'INFRASPECIFIC_NAME', 'INFRASUBSPECIFIC_NAME', 'KINGDOM', 'ORDER',
   *     'PHYLUM', 'SECTION', 'SERIES', 'SPECIES', 'STRAIN', 'SUBCLASS',
   *     'SUBFAMILY', 'SUBFORM', 'SUBGENUS', 'SUBKINGDOM', 'SUBORDER',
   *     'SUBPHYLUM', 'SUBSECTION', 'SUBSERIES', 'SUBSPECIES', 'SUBTRIBE',
   *     'SUBVARIETY', 'SUPERCLASS', 'SUPERFAMILY', 'SUPERORDER', 'SUPERPHYLUM',
   *     'SUPRAGENERIC_NAME', 'TRIBE', 'UNRANKED', 'VARIETY'.
   *   - 'limit' (integer): number of records to return. Default: 100. Maximum:
   *     1000 (optional).
   *   - 'offset' (integer): record number to start at (optional).
   * @param string $data