Models

Models

Models are the basic representation of interactions with the database. There are two types of models, a read-only model and a write-only model, which are both dynamically generated from a model schema.

Anatomy of a Model Schema

All model schemas are located in models/schema/ and extend the ModelSchema interface. Here's an example schema:

<?hh // strict

class ExampleSchema implements ModelSchema {
  public function getFields(): Map<string, ModelField> {
    return Map {
      'ID' => ModelField::int_field('id'),
      'Name' => ModelField::string_field('name'),
    };
  }

  public function getTableName(): string {
    return 'example';
  }

  public function getIdField(): string {
    return 'id';
  }
}

getIdField() and getTableName() are fairly self-descriptive, but let's take a closer look at getFields().

getFields()

public function getFields(): Map<string, ModelField> {
  return Map {
    'ID' => ModelField::int_field('id'),
    'Name' => ModelField::string_field('name'),
  };
}

Here we define a mapping between data fields in our model and the database columns, as well as establish types. In this example, ID will be an int, and will be generated into a getID() function in the read-only model, setID() in the write-only model, and will map to an int column in the database called id. Other types of field types can be found here.

Read-Only Models

For the above example, upon running our build script, a read-only model will be generated:

<?hh
/**
 * This file is partially generated. Only make modifications between BEGIN
 * MANUAL SECTION and END MANUAL SECTION designators.
 *
 * @partially-generated SignedSource<<7d8f29e8e807ty578602e6e5c9jk5a07>>
 */
final class Example {
  private function __construct(private Map<string, mixed> $data) {
  }

  public static function load(int $id): ?Example {
    $result = DB::queryFirstRow("SELECT * FROM example WHERE id=%s", $id);
    if (!$result) {
      return null;
    }
    return new Example(new Map($result));
  }

  public function getID(): int {
    return (int) $this->data['id'];
  }

  public function getName(): string {
    return (string) $this->data['name'];
  }

  /* BEGIN MANUAL SECTION Example_footer */
  /* END MANUAL SECTION */
}

To generate the object, we only have to call Example::load($id), and it will go out to the database and populate our object for us. Here, id is whatever we specified our ID Field to be in the schema. In the event we need to add additional methods to the model, we can do so between the two comments at the bottom of the class, and it will be carried over across re-generations of the file.

Write-Only Models (Mutators)