We’re getting ready for the next release of Omeka S. On the docket we have improvements to searching (like “fulltext” search support, and the ability to search for content within site pages and not just resources like items), improved support for using non-default properties as the “title” and “description” properties for resources, along with many other improvements.
Along with these we’re doing some updating to our core components, one in particular being Doctrine. Doctrine is the database layer for Omeka S, and in this release we’re updating to a more modern version. This comes along with some significant changes: this updated version requires PHP 7.1 or greater, and therefore so will Omeka. (Note: all older versions of PHP are currently not supported or updated by the PHP developers.) To ensure MySQL’s updated fulltext searching capability is available, we’re also increasing the MySQL version requirement to 5.6.
Most significantly, the Doctrine update makes a change to some internals used for querying the database, and this change may require updates to modules that currently use DQL or the Query Builder component. In particular, changes may be necessary for:
- modules that add their own API resource(s) that use the database, and
- modules that hook into the query process for other resources using the
api.search.queryorapi.find.queryevents
The specific change is as follows: The Omeka S API creates Doctrine DQL queries to communicate with the database to browse and retrieve resources. Every entity in a DQL query must have an associated “alias.” In current versions of Omeka S, the API uses the name of the entity class for a resource as this alias, accessible with the getEntityClass() method of the API adapter.
These “class name” aliases are no longer valid in the current version of Doctrine, and using them results in a “syntax error” from Doctrine. To account for this, we’ve changed Omeka S’s behavior so it no longer uses the class name aliases, and instead always uses the same alias for the “main” entity in a query: the string 'omeka_root'.
In general, modules should be able to make a simple change to accommodate this: replace calls to getEntityClass() in API code with 'omeka_root'. Usually these will be calls dealing with the Query Builder object (often assigned the variable $qb). The general places to check would be the buildQuery() and sortQuery() methods of API adapters, as well as event listeners for the api.search.query or api.find.query events.
The “develop” branch of Omeka S currently uses the updated version of Doctrine, so you can test against that version ahead of the release (make sure to update dependencies with gulp deps).
Because it requires updates to modules, this upcoming release of Omeka S will be version 2.0.0, an increment of the “major” version number. Our current plans call for a release in August. Updates to modules written by the Omeka team will release at the same time as the Omeka S core release.
Please get in touch, whether by responding on this thread or otherwise, if you have questions or concerns.