Entities

An entity is any type of object in the application, such as a submission, review assignment or discussion. Each entity consists of several files which describe its properties, read and write objects to the data store, and map the objects to different formats.

The example below shows the files you will find for the Publication object.

├─┬ /classes
│ │
│ └─┬ /publication
│   │
│   ├─┬ /maps
│   │ │
│   │ └── Schema.php    # Map a publication object to its schema properties (Optional)
│   │
│   ├── DAO.php         # Read/write publications to the data store
│   │
│   ├── Collector.php   # Build queries to get a collection of publications (Optional)
│   │
│   ├── Publication.php # The DataObject class for publications
│   │
│   └── Repository.php  # A repository to interact with publications
│
└─┬ /schemas
  │
  └──  publication.json # A JSON schema that describes a publication object

This chapter will discuss the DataObject and schema. Other chapters cover the DAOs/Collectors, Maps, and Repositories.

DataObject #

Each entity has a DataObject class to work with objects in the application.

DataObjects perform the role of Models in the MVC (Model-View-Controller) application architecture.

Use the repository to get a new object.

use APP\facades\Repo;

$publication = Repo::publication()->newDataObject();

// $publication is an instance of PKP\classes\publication\Publication

Set data on an object.

$publication->setData('copyrightYear', '2021');

Get data from an object.

$copyrightYear = $publication->getData('copyrightYear');

Multilingual data stores unique values for each locale. Get the value for a specific locale.

$title = $publication->getLocalizedData('title', 'en');

Omit the locale to get the value for the user’s currently active locale, or to fall back to the default locale.

$title = $publication->getLocalizedData('title');

The default locale is usually the context’s primary locale. However, data for a submission and related objects like authors and keywords will use the submission’s locale as the default.

Set localized data by passing all locales at once.

$publication->setData('title', [
  "en" => "Traditions and Trends in the Study of the Commons",
  "fr_CA" => "Traditions et tendances de l'étude des biens communs",
]);

Or specify a locale code when you set the data.

$journal->setData('title', 'Traditions and Trends in the Study of the Commons', 'en');

A DataObject class may add helper methods to return formatted data. For example, the Issue class provides a method that will return a string with the volume, number, year and title.

$issue->setData('volume', 3);
$issue->setData('number', 2);
$issue->setData('year', 1983);
$issue->setData('title', 'Special Issue on Microorganisms', 'en');

echo $issue->getIssueIdentification();
// Vol 3 No 2 (1983) Special Issue on Microorganisms

A DataObject class should never access the database directly. If a helper method requires another object, it should be passed as an argument to the method.

echo $publication->getAuthorString($authorUserGroups);
// D. Barnes (Author), C. Corino (Translator)

Schema #

Entities are defined by an extended version of json-schema, a JSON syntax for documenting the properties of an object. The json-schema syntax is documented in these examples.

JSON is similar to JavaScript, but uses a stricter syntax. Use JSONLint to identify errors in your schema.

A simple schema with two properties, id and title, would look like this.

{
  "title": "Publication",
  "description": "A published version of a submission.",
  "properties": {
    "id": {
      "type": "integer",
      "readOnly": true
    },
    "title": {
      "type": "string"
    }
  }
}

Add a multilingual attribute to properties that store data in more than one locale.

{
  ...
  "properties": {
    "title": {
      "type": "string",
      "multilingual": true
    }
  }
}

The application will support the expected property type for each enabled locale.

{
  "title": {
    "en": "Traditions and Trends in the Study of the Commons",
    "fr_CA": "Traditions et tendances de l'étude des biens communs"
  }
}

When an entitiy has a property in one application but not the other, use two schema files with the same name.

lib/pkp/schemas/context.json

{
	"title": "Context",
	"description": "A journal, press or preprint server.",
	"type": "object",
	"properties": {
		"about": {
			"type": "string",
			"multilingual": true
    }
  }
}

schemas/context.json

{
	"title": "Journal",
	"description": "A journal.",
	"properties": {
		"abbreviation": {
			"type": "string",
			"multilingual": true
    }
  }
}

We use a modified and extended version of the json-schema syntax. The following table describes these differences.

Learn how to read and write objects to the data store with a DAO.