# Mapping Overrides

For the most part, you will want to specify your [mapping information](/annotations.md) once, up-front. However, there may be occasions when you want to override mapping information programatically, perhaps to load records of a certain type from a different table than the one that is usually used (eg. when running integration tests). All of the attributes on [Table](/annotations/objectiphy-annotations.md#table), [Column](/annotations/objectiphy-annotations.md#column), and [Relationship](/annotations/objectiphy-annotations.md#relationship) definitions can be overridden in code, or by loading mapping information from a json file at runtime.

### Overriding Table Mapping

To override a mapping attribute for a table, set the [entity config option](/configuration-options.md#entity-config-options) with the attribute name and value required like this:

```php
$repository->setEntityConfigOption(
    MyEntity::class,
    ConfigEntity::TABLE_OVERRIDES,
    ['name' => 'alternative_table_name']
);
```

### Overriding Column Mapping

With columns (and relationships), you must also specify which property to apply the override to, so you must pass in a multi-dimensional array, like this:

```php
$repository->setEntityConfigOption(
    MyEntity::class,
    ConfigEntity::COLUMN_OVERRIDES,
    ['someProperty' => ['isReadOnly' => false]]
);
```

### Overriding Relationship Mapping

The same principle is used for relationships:

```php
$repository->setEntityConfigOption(
    MyEntity::class,
    ConfigEntity::RELATIONSHIP_OVERRIDES,
    [
        'user' => [
            'joinTable' => 'user_alternative',
            'sourceJoinColumn' => 'user_id',
            'targetJoinColumn' => 'id'
        ]
    ]
);
```

For all overrides, you can specify multiple override values simply by adding more elements to the override arrays you pass in.

### Overriding Mappings Using JSON Files

As well as programatically overriding individual mappings in code, you can tell Objectiphy to use a particular JSON file containing mapping information, or even to scan a directory to load mapping information for multiple classes at once. As with programmatic overrides, the mapping information provided using a JSON file will override any existing mapping information - you can combine mapping information on the entity with overridden mappings in a file (the file will take precedence).

The format of a JSON file for specifying mapping information is similar to the arrays described above. A mapping file should contain an element at the root level called `className` which holds the fully qualified class name of the entity to which the mapping relates. As siblings of that element, you can specify `table`, `column` and `relationship` elements with the mapping override information specified in the same way as shown above. For example:

```json
{
  "className": "App\\Entity\\MyEntity",
  "table": {
    "name": "alternative_table"
  },
  "relationships": {
    "user": {
      "joinTable": "user_alternative",
      "sourceJoinColumn": "user_id",
      "targetJoinColumn": "id"
    }
  },
  "columns": {
    "someProperty": {
      "isReadOnly": true
    },
    "someOtherProperty": {
      "name": "other_stuff",
      "dataMap": {
        "A": "The Letter A",
        "B": "The Letter B",
        "ELSE": "Some other letter"
      }
    }
  }
}
```

To specify a particular file to be used to override mappings for an entity, set the mapping file enitty config option, like this:

```php
$repository->setEntityConfigOption(
    MyEntity::class,
    ConfigEntity::MAPPING_FILE,
    '/my/project/directory/mapping/MyEntityMapping.json'
);
```

You can also use a general configuration option to load multiple mapping files for different entities by scanning a directory. When you do this, Objectiphy will look at all files in the directory and try to `json_decode` them and extract the value from `className`. If it cannot do that, the file will be ignored. Any sub-directories will be traversed, so make sure you use a directory that only contains the mapping files you want to use (but you can organise them into sub-directories if you wish). If the file can be decoded, and has a `className` element in the root, it will be loaded and the mapping information will be applied to the given entity class name. To specify a directory, set the main config option like this:

```php
$repository->setConfigOption(
    ConfigOptions::MAPPING_DIRECTORY,
    '/my/project/directory/mapping'
);
```

There is a performance sacrifice involved in applying mapping a runtime, so only do this if you need to, and try to avoid using it for very large object hierarchies.


---

# 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.objectiphy.net/mapping-overrides.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.