Repository navigation
8.1.3
8.1.3 adds a hook that rewrites the queries of a read. It changes nothing for a database without one; see
Upgrading from 8.1.2 to 8.1.3.
Added
Hook\Queries::rewrite(Event $event, Collection $collection, array $queries): arrayrewrites the queries of a
read, registered withaddHook()and removed withremoveHook(). It is given the queries one read was given and
the definition of the collection being read, once each query is checked to be aQueryand before the read checks
its queries any further: before it validates, parses or authorizes them or resolves their joins. The queries it
returns replace the read's queries for the rest of the read, the query-cache key included. It runs for
getDocument()(Event::DocumentRead),find()and sofindOne(),cursor()andresolveCursor()
(Event::DocumentFind),count()(Event::DocumentCount),sum()(Event::DocumentSum) andaggregate()
(Event::DocumentAggregate). Hooks run in registration order, each given the previous one's output. Throwing
refuses the read, with the exception reaching the caller unchanged before anything is read. It also runs on the
reads such a read makes itself: relationship population, the reads that resolve queries on relationship attributes,
findOne()throughfind(), eachcursor()page andresolveCursor()'s read of the joined row it pairs with the
document. So it must return the same queries when given its own output; it runs whether or not events are silenced.
It never runs for reads ofDatabase::METADATA, for thequery(),mutate()andfrom()builders, or for writes
and the reads they make themselves. The writes arecreateDocument(),createDocuments(),updateDocument(),
updateDocuments(),upsertDocument(),upsertDocuments(),increaseDocumentAttribute(),
decreaseDocumentAttribute(),deleteDocument()anddeleteDocuments(), and theauthorizeCreate(),
authorizeUpdate()andauthorizeGrants()checks of a later write; their own reads load the documents they change,
read back the ones they wrote, populate the relationships of the documents they return, and check, link and cascade
related documents, so a hook that hides rows never hides them from a write's permission and relationship checks. A
read the caller's own code makes while a write runs, such as in anonNextcallback, runs it. With such a hook
registered,cursor()resolves the collection and rewrites its queries when it is called, so a missing collection
or a refusal throws then instead of when the generator is iterated. AMirrorruns it once on each of its own reads
and never on its destination's. One that is also aHook\Lifecycleis registered on the source too, as every
lifecycle hook is, so it also rewrites the reads made on the source directly, except the reads the mirror's writes
make there.