Search

Searching through a parent

A searchable child declared with ThroughParent is found through the keys of its parent, and its documents follow the changes of the parent.
app/Access/Controls/CommentControl.php
protected function perimeters(): array
{
    return [
        ThroughParent::belongsTo('post', inverse: 'comments'),
    ];
}
app/Models/Comment.php
class Comment extends Model
{
    use HasControl, ControlledSearchable;
}

A searchable child declared with ThroughParent is found through its parent with the rule of the SQL: the parent's boundary and the parent's access keys must both open the parent for the reader. Comment::search('typo')->controlled() then finds the comments of the posts the reader may view.

The keys

The child's own filter is _boundary AND _access, and _access is a union, so each pair of a parent boundary key and a parent access key becomes one composite key in the child's _access:

Keys of the parentKeys of the child
Boundary workspace_id.1; access author.7, client.3through.post.2.workspace_id.1, through.post.2.workspace_id.1.author.7, through.post.2.workspace_id.1.client.3
No boundary; access client.3through.post.0, through.post.0.client.3

The reader builds the same keys from the parent's filter: through.post.2.workspace_id.1.author.7 for an author, and the boundary key alone, through.post.2.workspace_id.1, for a reader that the parent does not restrict.

  • The number after the relation counts the parts of the boundary key, 0 without a boundary, so a key always splits back into one boundary key and one access key.
  • Nested parents compose: a reply through its thread through its forum carries through.thread.0.through.forum.0.client.3.
  • A child carries, for each parent, the parent's boundary keys times its access keys plus one: usually one key more than the parent has.
  • through is reserved: a perimeter of a control with a ThroughParent that names its keys through throws DuplicateSearchKeyNameException.
  • Each key is stored as its digest, like every key.

The relation is loaded with the parent's own load relations when the child is indexed. A soft-deleted parent is not loaded, so its children lose the keys they inherit from it.

Requirements

On a searchable child, the control throws UnsearchableThroughParentException when it is built:

  • when a ThroughParent has no inverse, or a parent further up the chain has none;
  • when it delegates view to another ability of the parent: a search only knows the keys that open the parent for view;
  • when the parent's boundary has no search form.

The control of a searchable child watches its parent and the models its parent watches, so it must be discovered, like a control that declares reindexWhen().

Following the parent

The children follow their parent through jobs queued after the commit, unique and in chunks, as for reindexWhen():

  • The parent's keys change. On each update of the parent, the package compares the parent's keys before and after it, and reindexes the children through inverse when they differ. An update that leaves the keys unchanged queues nothing, and creating a parent queues nothing.
  • The parent is reindexed by its own reindexWhen(). When a grandparent changes, the children of the rows that the parent's rule reindexes are reindexed too, through every level. The parent needs neither to be searchable nor to be discovered: a control whose model does not use ControlledSearchable may declare reindexWhen() when a searchable child inherits its keys through a ThroughParent with inverse.
  • The parent is deleted, soft deleted or restored. Its children are reindexed, and lose or regain the keys they inherit.
  • A child moves to another parent. Scout reindexes the child itself, as any saved model.

A foreign key that the database sets to null on its own, without an Eloquent event, is not seen: reindex those children yourself.

Children of several brands

The through keys carry nothing of the child's own brand. When the control of the parent reads the brands of the request, decide the parent in the brand of each child row with decidedInRowContext(): the keys then hold the value of the row after the relation, such as through.post.in.1.2.workspace_id.1.author.7. See Row context.

Testing

assertSearchAgrees() compares the search with the SQL on a searchable child as on any model:

$this->assertSearchAgrees(CommentControl::class, readers: [$this->author, $this->manager, $this->admin]);