Build an empty object.

Establish a live connection to a database service. This method should return a new connection. Lisk handles connection caching and management; do not perform caching deeper in the stack.

Return a namespace for this object's connections in the connection cache. Generally, the database name is appropriate. Two connections are considered equivalent if they have the same connection namespace and mode.

Get an existing, cached connection for this object.

Store a connection in the connection cache.

Force an object to use a specific connection.

This overrides all connection management and forces the object to use a specific connection when interacting with the database.

Change Lisk behaviors, like ID configuration and timestamps. If you want to change these behaviors, you should override this method in your child class and change the options you're interested in. For example:

protected function getConfiguration() {
  return array(
    Lisk_DataAccessObject::CONFIG_EXAMPLE => true,
  ) + parent::getConfiguration();
}

The available options are:

CONFIG_IDS Lisk objects need to have a unique identifying ID. The three mechanisms available for generating this ID are IDS_AUTOINCREMENT (default, assumes the ID column is an autoincrement primary key), IDS_MANUAL (you are taking full responsibility for ID management), or IDS_COUNTER (see below).

InnoDB does not persist the value of auto_increment across restarts, and instead initializes it to MAX(id) + 1 during startup. This means it may reissue the same autoincrement ID more than once, if the row is deleted and then the database is restarted. To avoid this, you can set an object to use a counter table with IDS_COUNTER. This will generally behave like IDS_AUTOINCREMENT, except that the counter value will persist across restarts and inserts will be slightly slower. If a database stores any DAOs which use this mechanism, you must create a table there with this schema:

CREATE TABLE lisk_counter (
  counterName VARCHAR(64) COLLATE utf8_bin PRIMARY KEY,
  counterValue BIGINT UNSIGNED NOT NULL
) ENGINE=InnoDB DEFAULT CHARSET=utf8;

CONFIG_TIMESTAMPS Lisk can automatically handle keeping track of a `dateCreated' and `dateModified' column, which it will update when it creates or modifies an object. If you don't want to do this, you may disable this option. By default, this option is ON.

CONFIG_AUX_PHID This option can be enabled by being set to some truthy value. The meaning of this value is defined by your PHID generation mechanism. If this option is enabled, a `phid' property will be populated with a unique PHID when an object is created (or if it is saved and does not currently have one). You need to override generatePHID() and hook it into your PHID generation mechanism for this to work. By default, this option is OFF.

CONFIG_SERIALIZATION You can optionally provide a column serialization map that will be applied to values when they are written to the database. For example:

self::CONFIG_SERIALIZATION => array(
  'complex' => self::SERIALIZATION_JSON,
)

This will cause Lisk to JSON-serialize the 'complex' field before it is written, and unserialize it when it is read.

CONFIG_BINARY You can optionally provide a map of columns to a flag indicating that they store binary data. These columns will not raise an error when handling binary writes.

CONFIG_COLUMN_SCHEMA Provide a map of columns to schema column types.

CONFIG_KEY_SCHEMA Provide a map of key names to key specifications.

CONFIG_NO_TABLE Allows you to specify that this object does not actually have a table in the database.

CONFIG_NO_MUTATE Provide a map of columns which should not be included in UPDATE statements. If you have some columns which are always written to explicitly and should never be overwritten by a save(), you can specify them here. This is an advanced, specialized feature and there are usually better approaches for most locking/contention problems.

Determine the setting of a configuration option for this class of objects.

Load an object by ID. You need to invoke this as an instance method, not a class method, because PHP doesn't have late static binding (until PHP 5.3.0). For example:

$dog = id(new Dog())->load($dog_id);

Loads all of the objects, unconditionally.

Load all objects which match a WHERE clause. You provide everything after the 'WHERE'; Lisk handles everything up to it. For example:

$old_dogs = id(new Dog())->loadAllWhere('age > %d', 7);

The pattern and arguments are as per queryfx().

Load a single object identified by a 'WHERE' clause. You provide everything after the 'WHERE', and Lisk builds the first half of the query. See loadAllWhere(). This method is similar, but returns a single result instead of a list.

Reload an object from the database, discarding any changes to persistent properties. This is primarily useful after entering a transaction but before applying changes to an object.

Initialize this object's properties from a dictionary. Generally, you load single objects with loadOneWhere(), but sometimes it may be more convenient to pull data from elsewhere directly (e.g., a complicated join via queryData()) and then load from an array representation.

Initialize a list of objects from a list of dictionaries. Usually you load lists of objects with loadAllWhere(), but sometimes that isn't flexible enough. One case is if you need to do joins to select the right objects:

function loadAllWithOwner($owner) {
  $data = $this->queryData(
    'SELECT d.*
      FROM owner o
        JOIN owner_has_dog od ON o.id = od.ownerID
        JOIN dog d ON od.dogID = d.id
      WHERE o.id = %d',
    $owner);
  return $this->loadAllFromArray($data);
}

This is a lot messier than loadAllWhere(), but more flexible.

This method helps to prevent the 1+N queries problem. It happens when you execute a query for each row in a result set. Like in this code:

$diffs = id(new DifferentialDiff())->loadAllWhere(
  'revisionID = %d',
  $revision->getID());
foreach ($diffs as $diff) {
  $changesets = id(new DifferentialChangeset())->loadAllWhere(
    'diffID = %d',
    $diff->getID());
  // Do something with $changesets.
}

One can solve this problem by reading all the dependent objects at once and assigning them later:

$diffs = id(new DifferentialDiff())->loadAllWhere(
  'revisionID = %d',
  $revision->getID());
$all_changesets = id(new DifferentialChangeset())->loadAllWhere(
  'diffID IN (%Ld)',
  mpull($diffs, 'getID'));
$all_changesets = mgroup($all_changesets, 'getDiffID');
foreach ($diffs as $diff) {
  $changesets = idx($all_changesets, $diff->getID(), array());
  // Do something with $changesets.
}

The method loadRelatives() abstracts this approach which allows writing a code which is simple and efficient at the same time:

$diffs = $revision->loadRelatives(new DifferentialDiff(), 'revisionID');
foreach ($diffs as $diff) {
  $changesets = $diff->loadRelatives(
    new DifferentialChangeset(),
    'diffID');
  // Do something with $changesets.
}

This will load dependent objects for all diffs in the first call of loadRelatives() and use this result for all following calls.

The method supports working with set of sets, like in this code:

$diffs = $revision->loadRelatives(new DifferentialDiff(), 'revisionID');
foreach ($diffs as $diff) {
  $changesets = $diff->loadRelatives(
    new DifferentialChangeset(),
    'diffID');
  foreach ($changesets as $changeset) {
    $hunks = $changeset->loadRelatives(
      new DifferentialHunk(),
      'changesetID');
    // Do something with hunks.
  }
}

This code will execute just three queries - one to load all diffs, one to load all their related changesets and one to load all their related hunks. You can try to write an equivalent code without using this method as a homework.

The method also supports retrieving referenced objects, for example authors of all diffs (using shortcut loadOneRelative()):

foreach ($diffs as $diff) {
  $author = $diff->loadOneRelative(
    new PhabricatorUser(),
    'phid',
    'getAuthorPHID');
  // Do something with author.
}

It is also possible to specify additional conditions for the WHERE clause. Similarly to loadAllWhere(), you can specify everything after WHERE (except LIMIT). Contrary to loadAllWhere(), it is allowed to pass only a constant string (% doesn't have a special meaning). This is intentional to avoid mistakes with using data from one row in retrieving other rows. Example of a correct usage:

$status = $author->loadOneRelative(
  new PhabricatorCalendarEvent(),
  'userPHID',
  'getPHID',
  '(UNIX_TIMESTAMP() BETWEEN dateFrom AND dateTo)');

Load referenced row. See loadRelatives() for details.

Set unique ID identifying this object. You normally don't need to call this method unless with IDS_MANUAL.

Retrieve the unique ID identifying this object. This value will be null if the object hasn't been persisted and you didn't set it manually.

Test if a property exists.

Retrieve a list of all object properties. This list only includes properties that are declared as protected, and it is expected that all properties returned by this function should be persisted to the database. Properties that should not be persisted must be declared as private.

Check if a property exists on this object.

Get or build the database connection for this object.

Convert this object into a property dictionary. This dictionary can be restored into an object by using loadFromArray() (unless you're using legacy features with CONFIG_CONVERT_CAMELCASE, but in that case you should just go ahead and die in a fire).

Make an object read-only.

Making an object ephemeral indicates that you will be changing state in such a way that you would never ever want it to be written back to the storage.

Persist this object to the database. In most cases, this is the only method you need to call to do writes. If the object has not yet been inserted this will do an insert; if it has, it will do an update.

Save this object, forcing the query to use REPLACE regardless of object state.

Save this object, forcing the query to use INSERT regardless of object state.

Save this object, forcing the query to use UPDATE regardless of object state.

Delete this object, permanently.

Internal implementation of INSERT and REPLACE.

Method used to determine whether to insert or update when saving.

Retrieve the database table name. By default, this is the class name.

Retrieve the primary key column, "id" by default. If you can not reasonably name your ID column "id", override this method.

Generate a new PHID, used by CONFIG_AUX_PHID.

Hook to apply serialization or validation to data before it is written to the database. See also willReadData().

Hook to perform actions after data has been written to the database.

Hook to make internal object state changes prior to INSERT, REPLACE or UPDATE.

Hook to apply serialization or validation to data as it is read from the database. See also willWriteData().

Hook to perform an action on data after it is read from the database.

Hook to perform an action before the deletion of an object.

Hook to perform an action after the deletion of an object.

Reads the value from a field. Override this method for custom behavior of getField() instead of overriding getField directly.

Writes a value to a field. Override this method for custom behavior of setField($value) instead of overriding setField directly.

Increase transaction stack depth.

Decrease transaction stack depth, saving work.

Decrease transaction stack depth, discarding work.

Begins read-locking selected rows with SELECT ... FOR UPDATE, so that other connections can not read them (this is an enormous oversimplification of FOR UPDATE semantics; consult the MySQL documentation for details). To end read locking, call endReadLocking(). For example:

$beach->openTransaction();
  $beach->beginReadLocking();

    $beach->reload();
    $beach->setGrainsOfSand($beach->getGrainsOfSand() + 1);
    $beach->save();

  $beach->endReadLocking();
$beach->saveTransaction();

Ends read-locking that began at an earlier beginReadLocking() call.

Begins write-locking selected rows with SELECT ... LOCK IN SHARE MODE, so that other connections can not update or delete them (this is an oversimplification of LOCK IN SHARE MODE semantics; consult the MySQL documentation for details). To end write locking, call endWriteLocking().

Ends write-locking that began at an earlier beginWriteLocking() call.

Close any connections with no recent activity.

Long-running processes can use this method to clean up connections which have not been used recently.

Applies configured serialization to a dictionary of values.

Black magic. Builds implied get*() and set*() for all properties.

Warns against writing to undeclared property.

Increments a named counter and returns the next value.

Returns the current value of a named counter.

Overwrite a named counter, forcing it to a specific value.

If the counter does not exist, it is created.

Break a list of escaped SQL statement fragments (e.g., VALUES lists for INSERT, previously built with qsprintf()) into chunks which will fit under the MySQL 'max_allowed_packet' limit.

Chunks are glued together with $glue, by default ", ".

If a statement is too large to fit within the limit, it is broken into its own chunk (but might fail when the query executes).