# Doctrine Utils

## Doctrine Utils

Siteadmin 3 using [Doctrine 2](http://docs.doctrine-project.org/en/latest) as the ORM of choice. The `doctrineUtils` helper encapsulates a collection of functions that preform common operations with a doctrine entity. These operations range from converting an entity to an array to retrieving data store information about an entity.

### Convert entity to array

```php
doctrineUtils::getEntityArray(
    $entity,
    $includeAssociations,
    $useProxyIds,
    $associationConfiguration
);
```

| Parameter                   | Type    | Required | Description                                                                                                                                                                                                                                                                                            |
| --------------------------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `$entity`                   | Object  | yes      | The doctrine entity to be converted.                                                                                                                                                                                                                                                                   |
| `$includeAssociations`      | boolean | no       | Default: `false`. If true, associated objects will be included in the converted array. For example, a user may have an association with posts. When converting the user object to an array, this flag must be set to true to include the user's posts. > Only in-memory associations will be included. |
| `$useProxyIds`              | boolean | no       | Default: `false`. If true, the real IDs of the base entity and associated entities will be replaced with UUIDs. The [UUID Proxy documentation](https://app.gitbook.com/s/-LB7PTje97ARlss-zn8u/developer-guide/utilities-and-helpers/uuid_proxy.md) describes how to access content from these UUIDs.   |
| `$associationConfiguration` | array   | no       | Default: `[]`. A key/value map containing a list of entities that should be included in the object to array conversion. See association configuration guide for more information.                                                                                                                      |

#### Association Configuration

The `$associationConfiguration` parameter in `getEntityArray()` is a map of entities which are allowed to be included in the object to array conversion process. This allows you to exclude unwanted data sets from the parsing process.

**Example**

```php
<?php
class User {
    /** @var  int */
    protected $id;
    
    /** @var  string */
    protected $name;
    
    /** @var  Post[] */
    protected $posts;
    
    /** @var  User[] */
    protected $followers;
}
​
function parseUserAsArray(User $user) {
    $assocConf = array(
        'followers' => 'object'
    );
    
    return doctrineUtils::getEntityArray($user, true, false, $assocConf);
}
```

The code snippet above will parse the user's `id`, `name`, and `followers` fields into an array. The `posts` property will be ignored, because it is not included in the association configuration.

> Notice the association configuration is a key/value pair, where the key is the name of the associated entity, and the value is its type. The value will almost always be `object`.

**Result**

You may assume the user's ID is `12`.

```
{
  "12": {
    "id": 12,
    "name": "John Doe",
    "followers": [
      <list of followers>
    ]
  }
}
```

### Convert entity collection to array

```php
doctrineUtils::getEntityCollectionArray(
    $collection,
    $includeAssociation,
    $associationConfiguration
);
```

| Parameter                   | Type    | Required | Description                                                                                                                                                                                                                                                                                            |
| --------------------------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `$entity`                   | Object  | yes      | The doctrine entity to be converted.                                                                                                                                                                                                                                                                   |
| `$includeAssociations`      | boolean | no       | Default: `false`. If true, associated objects will be included in the converted array. For example, a user may have an association with posts. When converting the user object to an array, this flag must be set to true to include the user's posts. > Only in-memory associations will be included. |
| `$associationConfiguration` | array   | no       | Default: `[]`. A key/value map containing a list of entities that should be included in the object to array conversion. See association configuration guide for more information.                                                                                                                      |

### Set entity properties from array

Given a property map with the format \[propertyName => value], calls the setters on the given entity with the passed value data.

```php
doctrineUtils::setEntityData($properties, $entity, $useBlankFields);
```

| Paremeter         | Type    | Required | Description                                                                                                                                             |
| ----------------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `$properties`     | array   | yes      | A set of key/value pairs, representing an entity's properties and their corresponding values.                                                           |
| `$entity`         | Object  | yes      | A doctrine entity.                                                                                                                                      |
| `$useBlankFields` | boolean | no       | Default: `false`. If false, keys with empty values will skipped. If true, the empty values will replace the value of the corresponding object property. |

#### Example

```php
<?php
class User {
    protected $firstName;
    protected $nickname;
    private $lastName;
    public $age;
}
​
$user = new User();
$user->setFirstName('John')
     ->setLastName('Doe')
     ->setNickname('Bobby')
     ->setAge(30);
​
$properties = array(
    'nickname'  => null,
    'age'       => 25
);
​
// Age is changed from 30 to 25.
// Nickname is skipped since the new value is null|0|false.
doctrineUtils::setEntityData($properties, $user);
​
// Age is changed from 30 to 25.
// Nickname is changed from 'Bobby' to null.
doctrineUtils::setEntityData($properties, $user, true);
​
// Create a new user object from property map.
$user2 = doctrineUtils::setEntityData($properties, new User(), true);
```

### Get entity meta data

Retrieves information about an entity's methods and properties.

```php
doctrineUtils:getEntityInfo($entity)
```