# Services

farmOS provides some [services](https://symfony.com/doc/current/service_container.html)
that encapsulate common logic like querying logs and getting an asset's current
location. Some of these services are documented here.

## Asset logs service

**Service name**: `asset.logs`

The asset logs service provides methods for retrieving logs that reference
assets.

**Methods**:

`getLogs($asset, $log_type = NULL, $access_check = TRUE)` - Load a list of logs
that reference an asset, optionally filtered by log type. Access checking is
performed by default but can be optionally disabled. Returns a list of log
entities.

`getFirstLog($asset, $log_type = NULL, $access_check = TRUE)` - Load the first
log that references an asset, optionally filtered by log type. Access checking
is performed by default but can be optionally disabled. Returns a log entity, or
`NULL` if no logs were found.

**Example usage**:

```php
// Get all observation logs that reference an asset.
$observation_logs = \Drupal::service('asset.logs')->getLogs($asset, 'observation');
```

## Asset location service

**Service name**: `asset.location`

The asset location service provides methods that encapsulate the logic for
determining an asset's location and geometry.

Note that these methods do not perform access checking on any of the assets or
logs used to determine location. It is up to downstream code to ensure access
controls are respected.

**Methods**:

`isLocation($asset)` - Check if an asset is a location. Returns a boolean.

`isFixed($asset)` - Check if an asset is fixed. Returns a boolean.

`hasLocation($asset, $timestamp = NULL)` - Check if an asset is located within
other location assets, optionally at a given timestamp (defaults to current
time). Returns a boolean.

`hasGeometry($asset, $timestamp = NULL)` - Check if an asset has geometry,
optionally at a given timestamp (defaults to current time). Returns a boolean.

`getLocation($asset, $timestamp = NULL)` - Get location assets that an asset is
located within, optionally at a given timestamp (defaults to current time).
Returns an array of asset entities.

`getGeometry($asset, $timestamp = NULL)` - Get an asset's geometry, optionally
at a given timestamp (defaults to current time). Returns a Well-Known Text
string.

`getMovementLog($asset, $timestamp = NULL)` - Find the latest movement log that
references an asset, optionally at a given timestamp (defaults to current
time). Returns a log entity, or `NULL` if no logs were found.

`setIntrinsicGeometry($asset, $wkt)` - Set an asset's intrinsic geometry, given
a string in Well-Known Text format.

`getAssetsByLocation($locations, $timestamp = NULL)` - Get assets that are in
locations, optionally at a given timestamp (defaults to current time).

**Example usage**:

```php
// Get an asset's current geometry.
$geometry = \Drupal::service('asset.location')->getGeometry($asset);
```

## Asset inventory service

**Service name**: `asset.inventory`

The asset inventory service provides methods that encapsulate the logic for
determining an asset's inventory.

Note that these methods do not perform access checking on any of the assets or
logs used to determine inventory. It is up to downstream code to ensure access
controls are respected.

**Methods**:

`getInventory($asset, $measure = '', $units = 0, $timestamp = NULL)` - Get
inventory summaries for an asset, optionally at a given timestamp (defaults
to current time). Returns an array of arrays with the following keys:
`measure`, `value`, `units`. This can be optionally filtered by `$measure`
(string) and `$units` (term ID).

**Example usage**:

```php
// Get summaries of all inventories for an asset.
$all_inventory = \Drupal::service('asset.inventory')->getInventory($asset);

// Get the current inventory for a given measure (string) and units (term id).
$gallons_of_fertilizer = \Drupal::service('asset.inventory')->getInventory($asset, 'volume', 123);
```

## Field factory service

**Service name**: `farm_field.factory`

The field factory service provides two methods to make the process of creating
Drupal entity base and bundle field definitions easier and more consistent in
farmOS. This is used by modules that add [fields](/development/module/fields)
to [entity types](/development/module/entities).

Base fields are added to *all* bundles of a given entity type (eg: all logs).
Bundle fields are only added to *specific* bundles (eg: only "Input" logs).

Using this service is optional. It simply generates instances of Drupal core's
`BaseFieldDefinition` class or the Entity API module's `BundleFieldDefinition`
class, with farmOS-specific opinions to help enforce some consistency among
farmOS core and contrib modules. You can create instances of these field
definition classes directly instead of using the farmOS field factory service.
Or you can take the object produced by the service and customize it further
using standard Drupal field definition methods. This service is provided only
as a shortcut.

For more information on Drupal core's field definition API, see
[Drupal FieldTypes, FieldWidgets and FieldFormatters](https://www.drupal.org/docs/drupal-apis/entity-api/fieldtypes-fieldwidgets-and-fieldformatters)

**Methods**:

`baseFieldDefinition($options)` - Generates a base field definition, given an
array of options (see below).

`bundleFieldDefinition($options)` - Generates a bundle field definition, given
an array of options (see below).

**Options**:

Both methods expect an array of field definition options. These include:

- `type` (required) - The field data type. Each type may require additional
  options. Supported types include:
    - `boolean` - True/false checkbox.
    - `decimal` - Decimal number with fixed precision. Additional options:
        - `precision` (optional) - Total number of digits (including after the
          decimal point). Defaults to 10.
        - `scale` (optional) - Number digits to the right of the decimal point.
          Defaults to 2.
        - `min` (optional) - The minimum value.
        - `max` (optional) - The maximum value.
    - `email` - Email field.
    - `entity_reference` - Reference other entities. Additional options:
        - `target_type` (required) - The entity type to reference (eg: `asset`,
          `log`, `plan`)
        - `target_bundle` (optional) - The allowed target bundle. For example,
          a `target_type` of `asset` and a `target_bundle` of `animal` would
          limit references to animal assets.
        - `auto_create` (optional) Only used when `target_type` is set to
          `taxonomy_term`. If `auto_create` is set, term references will be
          created automatically if the term does not exist.
    - `file` - File upload.
    - `fraction` - High-precision decimal number storage.
    - `geofield` - Geometry on a map.
    - `image` - Image upload.
    - `integer` - Integer number. Additional options:
        - `size` (optional) - The integer database column size (`tiny`,
          `small`, `medium`, `normal`, or `big`). Defaults to `normal`.
        - `min` (optional) - The minimum value.
        - `max` (optional) - The maximum value.
    - `list_string` - Select list with allowed values. Additional options:
        - `allowed_values` - An associative array of allowed values.
        - `allowed_values_function` - The name of a function that returns an
          associative array of allowed values.
    - `string` - Unformatted text field of fixed length. Additional options:
        - `max_length` - Maximum length. Defaults to 255.
    - `string_long` - Unformatted text field of unlimited length.
    - `text_long` - Formatted text field of unlimited length.
    - `timestamp` - Date and time.
    - `uri` - Uniform Resource Identifier.
- `label` - The field label.
- `description` - The field description.
- `required` - Whether the field is required.
- `multiple` - Whether the field should allow multiple values. Defaults to
  `FALSE`.
- `cardinality` - How many values are allowed (eg: `1` for single value
  fields, `-1` for unlimited values). This is an alternative to `multiple`,
  and will take precedence if it is set. Defaults to `1`.

Other options are available for more advanced use-cases. Refer to the
[FarmFieldFactory](https://github.com/farmOS/farmOS/blob/4.x/modules/core/field/src/FarmFieldFactory.php)
class to understand how they work.

For more information and example code, see [Adding fields](/development/module/fields).

## Group membership service

**Service name**: `group.membership`

The group membership service provides methods that encapsulate the logic for
determining an asset's group membership. This is provided by the optional Group
Asset module, and will only be available if that module is installed.

Note that these methods do not perform access checking on any of the assets or
logs used to determine group membership. It is up to downstream code to ensure
access controls are respected.

**Methods**:

`hasGroup($asset, $timestamp = NULL)` - Check if an asset is a member of a
group, optionally at a given timestamp (defaults to current time). Returns a
boolean.

`getGroup($asset, $timestamp = NULL)` - Get group assets that an asset is a
member of, optionally at a given timestamp (defaults to current time). Returns
an array of asset entities.

`getGroupAssignmentLog($asset, $timestamp = NULL)` - Find the latest group
assignment log that references an asset, optionally at a given timestamp
(defaults to current time). Returns a log entity, or `NULL` if no logs were
found.

`getGroupMembers($groups, $recurse = TRUE, $timestamp = NULL)` - Get assets that
are members of groups, optionally recursing into child groups, and optionally
at a given timestamp (defaults to current time).

**Example usage:**

```php
// Get the groups that an asset is a member of.
$groups = \Drupal::service('group.membership')->getGroup($asset);
```
