APPNETOS is under active development This website and its documentation are being prepared for public launch. Content and features may change.
Select Theme
Loading

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
{
}
APPNETOS concrete Document and Collection classes extend their base classes and reference each other through Database annotations; Collections manage in-memory reuse and persistence.
Bidirectional annotation mapping between concrete Document and Collection classes, with request-local reuse and optional Redis caching.

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

Next Steps

Previous

Document

Explore Document

Next

Pipeline

Explore Pipeline