# 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)
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.siteadministrator.com/developer-guide/utilities-and-helpers/doctrine-utils.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.