<?php

namespace Squirrel\Entities;

/**

* INTERFACE: Multiple repositories should be read from (SELECT)

*/

interface MultiRepositoryReadOnlyInterface

{

/**

* Count number of entries. The options can be:

*

* - 'repositories': involved repositories as a name to RepositoryReadOnly / RepositoryBuilderReadOnlyInterface list

* - 'tables': how tables are connected and which are selected (optional, default is all)

* - 'where': WHERE restrictions

* - 'lock': if to lock selected entries (SELECT ... FOR UPDATE) for transaction (optional)

*

* @param array $query

* @psalm-param array{repositories:array,tables?:array,where:array,lock?:bool} $query

* @return int

*/

public function count(array $query): int;

/**

* Select query. The options can be:

*

* - 'repositories': involved repositories as a name to RepositoryReadOnly / RepositoryBuilderReadOnlyInterface list

* - 'tables': how tables are connected and which are selected (optional, default is all)

* - 'fields': what to select as a name to field name list

* - 'where': WHERE restrictions

* - 'group': GROUP BY definitions (optional)

* - 'order': ORDER BY definitions (optional)

* - 'limit': how many results to get (optional)

* - 'offset': at what record number to start (optional)

* - 'lock': if to lock selected entries (SELECT ... FOR UPDATE) for transaction (optional)

*

* A special possibility is a freeform query, with the following options:

*

* - 'repositories': involved repositories as a name to RepositoryConfigInterface list

* - 'fields': what to select as a name to field name list

* - 'query': Query as a string

* - 'parameters': Array of query value parameters

* - 'lock': if to lock selected entries (SELECT ... FOR UPDATE) for transaction (optional)

*

* Freeform queries should almost never be necessary and are not recommended, yet it is still a possibility

* because some queries (for example with subqueries or other complicated parts) cannot be structured yet might

* still be necessary or useful for performance or other reasons

*

* @param array $query

* @psalm-param array{repositories:array,tables?:array,fields:array,where?:array,group?:array,order?:array,limit?:int,offset?:int,lock?:bool,query?:string,parameters?:array} $query

* @return MultiRepositorySelectQueryInterface

*/

public function select(array $query): MultiRepositorySelectQueryInterface;

/**

* Find one entry from a result set and return it as an array

*

* @param MultiRepositorySelectQueryInterface $selectQuery

* @return array|null

*/

public function fetch(MultiRepositorySelectQueryInterface $selectQuery): ?array;

/**

* Clear existing result set

*

* @param MultiRepositorySelectQueryInterface $selectQuery

*/

public function clear(MultiRepositorySelectQueryInterface $selectQuery): void;

/**

* Select query and return one entry. The query options are the same as with the select function

*

* @param array $query

* @psalm-param array{repositories:array,tables?:array,fields:array,where?:array,group?:array,order?:array,limit?:int,offset?:int,lock?:bool,query?:string,parameters?:array} $query

* @return array

*/

public function fetchOne(array $query): ?array;

/**

* Select query and return all entries. The query options are the same as with the select function.

*

* @param array $query

* @psalm-param array{repositories:array,tables?:array,fields:array,where?:array,group?:array,order?:array,limit?:int,offset?:int,lock?:bool,query?:string,parameters?:array} $query

* @return array<int, array<string, mixed>>

*/

public function fetchAll(array $query): array;

/**

* Select query and return all entries as flattened values (no field names)

*

* @param array $query

* @psalm-param array{repositories:array,tables?:array,fields:array,where?:array,group?:array,order?:array,limit?:int,offset?:int,lock?:bool,query?:string,parameters?:array} $query

* @return array<bool|int|float|string|null>

*/

public function fetchAllAndFlatten(array $query): array;

}