====== Instance class ======

The instance class is the base class of an application build on Platform, and typically the application either consists of a single instance which have been pre-initiated or of several instances which are initialized when requested.

Facebook could be an example of a single-instance application, as all users interact within the same application, while Slack could be considered a multi-instance application, as users interact inside their own group which is self-contained and not mixed with other Slack groups.

===== Setting up an instance =====

The Instance class is meant to be overridden with an implementation which fit the current app. In general the only function that should be overridden or extended is the ''initializeDatabase()'' function where one should call ensureInDatabase() on all [[datarecord_class|Datarecords]] which is part of the application.

===== Single instance-environment =====

In a single instance environment one needs to just initialize the instance once, typically in an install script. This is done by calling 

<code php>
$instance = Instance::initialize($title, $username, $password);
</code>

which will initialize a new instance with the given title and add a user to the instance with the given credentials. When a user then logs in, we need to select the instance by activating it.

<code php>
$instance = new Instance();
$instance->loadForRead(1); // This is the ID of the instance in the database, which will be 1 if this is the only instance you have initialized.
$instance->activate();
</code>

To upgrade the instance, for example to change database structures one can call

<code php>
$instance->initializeDatabase();
</code>

which would typically be done in an upgrade script.

===== Multi-instance environment =====

In a multi-instance environment instances are usually initialized on the fly when users are signing up for the application, so here we again need to use the ''initialize'' function which we should wire into an existing sign-up form. 

<code php>
$existing_instance = Instance::getByTitle($requested_instance_title_from_form);
if ($existing_instance) {
  // Instance title in use. User should select another instance title.
} else {
  $instance = Instance::initialize($requested_instance_title_from_form, $requested_username, $requested_password);
}
</code>

When upgrading instances, we should call ''InitializeDatabase'' on each instance. An easy strategy to do this, is to call it every time a user log in, to ensure that the database is always initialized to the newest version.

When a user wants to cancel an instance, it is as simple as deleting it, which will also remove the database and all files.

<code php>
$instance->delete();
</code>

===== Logging into an instance =====

There are two easy ways of logging into an instance. A static function or a normal function.

<code php>
Instance::loginToInstance($instance_title, $username, $password, $continue_url);

$instance = new Instance();
$instance->loadForRead(1);
$instance->login($username, $password, $continue_url);
</code>

The function will return false if the provided username or password is invalid. Otherwise it will redirect to the ''$continue_url''. Please note that ''$continue_url'' must be an absolute URL with no hostname for everything to work correctly, such as ///application///

===== Multiserver environment =====

It is possible to have a range of servers, with each server holding one or more instances. This is implemented through the [[Server class]].

Each server should have the same copy of the source code.

When spawning a new instance using ''Instance::initialize'' the new instance will automatically be placed on the server with the least instances already. One can also provide a server id as the fourth parameter of ''Instance::initialize'' in order to place the instance on that specific server.