Collection
Queryless document management and intelligent reuse.
Concrete Collections extend Core\Collection\Base and declare the mapped Document class. They coordinate loading, writing, conversions, in-memory reuse and optional database caching.
Basic implementation
The following illustrates the relevant class relationship. Replace the example classes with your application's concrete types.
#[\Core\Collection\Annotation\Database(document: ExampleDocument::class)]
class ExampleCollection extends \Core\Collection\Base
{
}
Annotation-based mapping
Core\Collection\Annotation\Database specifies the Document class and can optionally select database and database-cache controllers. Concrete Collections extend Core\Collection\Base; application code normally interacts with these classes rather than constructing raw queries.
Memory-first loading
Collections maintain request-local documents. Cached objects can be resolved by ID, registered manually and cleared when needed. This reduces repeated document loading within a request.
Persistence and change tracking
insert(), update(), insertOrUpdate() and delete() manage Document persistence. The Collection tracks original document state and can generate targeted changes for updates; write operations coordinate cache synchronization and invalidation.
Read operations
findOneById(), findByIds(), findOneBy(), findBy() and findLatestCreated() offer convenient retrieval. find(), findOne(), count(), distinct() and aggregate() expose more advanced database capabilities when required.
Filter, Search and Pagination
The Filter helper builds MongoDB-compatible conditions. Search and Pagination are configuration/result objects; Collection::searchPaginated() and Collection::paginate() execute the corresponding work.
REST integration and conversion
REST-oriented operations support reading, creation, validation, updating, replacing and deletion. Conversion helpers map arrays, MongoDB values, ObjectIds and template data.
Caching boundaries
The request-local Collection cache is distinct from optional Redis database caching. Cache hits avoid repeated database work; misses or uncached operations still reach MongoDB.
Public API Reference
Public methods declared by Core\Collection\Base. Inherited methods are not repeated
here.
Signatures follow the uploaded source implementation.
| Method | Description |
|---|---|
public function __construct() |
Constructor |
public function init(): void |
Initialize collection |
public function getNew(): object |
Create mapped document instance |
public function paginate( Pagination $pagination, array|object|null $filter = [],
array|null $options = [], ): static |
Paginate documents |
public function searchPaginated( SearchPagination $search, array|null $options =
[],
): static |
Search paginated documents |
public function aggregate( array $pipeline, array|null $options = [], ):
array|null |
Aggregate |
public function findOne( array|null $filter = [], array|null $options = [], ):
object|null |
Find one document |
public function find( array|object|null $filter = [], array|null $options = [], ):
array|null |
Find multiple documents |
public function findOneById(ObjectId|string $id): object|null |
Find one document by ID |
public function findByIds(array $ids): array|null |
Find multiple documents by IDs |
public function findOneBy( string $key, mixed $value, ): object|null |
Find one document by key and value |
public function findBy( string $key, mixed $value, ): array|null |
Find multiple documents by key and value |
public function findLatestCreated(int $limit = 10): array |
Find latest created documents |
public function count( array|object|null $filter = null, array|null $options =
null,
): int |
Count collection entries |
public function distinct( string $field, array|object|null $filter = [],
array|null
$options = [], ): array|null |
Find distinct document field entries |
public function insert( object|array $documents, bool $clone = false, ):
object|array |
Insert |
public function update(object|array $documents): object|array |
Update one document or array of documents |
public function insertOrUpdate(object|array $documents): object|array |
Insert or update |
public function updateMany( object|array $filter, object|array $update, array
$options
= [], ): UpdateResult |
Update multiple documents |
public function updateOne( array|object|null $filter, array|object $update,
array|null
$options = [], ): object|null |
Update one document |
public function findOneAndUpdate( array|object|null $filter, array|object $update,
array|null $options = [], ): object|null |
Find and update one document atomically |
public function upsert( array|object|null $filter, array|object $update,
array|null
$options = [], ): object |
Update or insert one document atomically |
public function delete(object|array $documents): void |
Delete |
public function deleteOne( array $filter, array $options = [], ): void |
Delete one document |
public function deleteMany( array $filter, array $options = [], ): int |
Delete multiple documents |
public function addDocument(object $document): void |
Add a document to collection |
public function addDocuments(array $documents): void |
Add an array of documents to collection |
public function clearDocuments(): void |
Clear found documents cache |
public function clearDocument(ObjectId|string $id): static |
Clear cached document by ID |
public function getCachedDocumentById(ObjectId|string $id): object|null
|
Get cached document by ID |
public function findCachedDocument( array $filter, bool $findOne = false, ):
object|null |
Find cached document in memory cache |
public function search( array $filter, bool $find = false, ): array|null
|
Search multiple documents in found documents cache |
public function restFind( array|object|null $filter = [], array|null $options =
[], ):
array|null |
REST find documents |
public function restFindOneById(string|null $id): object|null |
REST find one document by ID |
public function restCreate(array $data): object|array |
REST create document |
public function restValidateCreate(array $data): void |
REST validate create data |
public function restUpdate( string|null $id, array $data, ): object|null
|
REST update document |
public function restValidateUpdate(array $data): void |
REST validate update data |
public function restReplace( string|null $id, array $data, ): object|null
|
REST replace document |
public function restDelete(string|null $id): bool |
REST delete document |
public function arrayToDocument(array $documentData): object |
Converts array with keys and values to document |
public function arrayToDocuments(array $documentsData): array |
Converts array of arrays with keys and values to array of documents |
public function documentToArray(object $document): array |
Convert a document to array with keys and values |
public function documentToMongoDb(object $document): object |
Convert a document to a MongoDB document |
public function documentToTemplateData(object $document): array |
Convert a document to an array of template data |
public function mongoDbValueToDocumentValue(mixed $value): mixed |
Convert a MongoDB value to a document value |
public function objectIdsToStrings(array $objectIds): array |
Convert an array of MongoDB ObjectIds to an array of strings |
public function objectIdToString(object $objectId): string |
Convert a MongoDB ObjectId to a string |
public function stringsToObjectIds(array $strings): array |
Convert an array of strings to MongoDB ObjectIds |
public function stringToObjectId(string $string): object |
Convert a string to a MongoDB ObjectId |
public function objectIdInObjectIds( ObjectId $objectId, array $objectIds, ):
bool |
Validate whether an ObjectId exists in an array of ObjectIds |
public function stringAsObjectId(string $string): bool |
Validate whether a string can be used as a MongoDB ObjectId |
public function getValidationOptions(string $field): array |
Get validation options |
public function getDocumentClassName(): string |
Get mapped document class name |
public function getMongoDbCollection(): object |
Get MongoDB collection |
public function getDocuments(): array |
Get found documents |
public function getCacheable(): bool |
Get document cacheable state |