✨ lazyloading of client and default to not read from cache

README.md

@@ -115,6 +115,77 @@ $pages = khulan([
 ]);
 ```
 
+### Example: Filtering and Resolving Relations
+
+With Kirby's content cache as a NoSQL database you can do some advanced filtering. If you would do the same with Kirby's
+filtering on collection you would end up loading a lot pages and that is not as efficient. We can load the information
+we need directly from the cache without the need to load the full page object.
+
+Let's assume we have two models: `film` and `actor`. The `film` model has a field `actors` which is a pages field with
+linked `actor` pages. We want to list all films with their actors.
+
+#### Load 1000 films and their actors, total of 6429 pages accessed in 250ms
+
+```php
+$films = page('films')->children();
+foreach ($films as $film) {
+ echo $film->title();
+ $actors = [];
+ foreach ($film->actors()->toPages() as $actor) {
+ $actors[] = $actor->title();
+ }
+ echo implode(', ', $actors);
+}
+?>
+```
+
+#### Query the cache instead to get the same information in under 100ms
+
+```php
+/** @var \MongoDB\Driver\Cursor $films */
+$films = khulan()->aggregate([
+ [
+ // only get pages with template 'film'
+ '$match' => ['template' => 'film'],
+ ],
+ [
+ // lookup actors by their mongodb objectId
+ // this will create an array of objects
+ '$lookup' => [
+ 'from' => 'kirby',
+ 'localField' => 'actors{}',
+ 'foreignField' => '_id',
+ 'as' => 'actor_details',
+ ],
+ ],
+ [
+ // only get the fields we need
+ // to make the query even faster
+ '$project' => [
+ 'title' => 1,
+ 'id' => 1,
+ 'actor_details.title' => 1,
+ ],
+ ],
+]);
+
+/** @var \MongoDB\BSON\Document $film */
+foreach ($films as $film) { ?>
+<div>
+ <a href="<?= url($film->id) ?>"><?= html($film->title) ?></a>
+ <ul>
+ <?php foreach ($film->actor_details as $actor) { ?>
+ <li><?= html($actor->title) ?></li>
+ <?php } ?>
+ </ul>
+</div>
+<?php }
+```
+
+> [!NOTE]
+>
+> This example is from [my Sakila DB kit](https://github.com/bnomei/kirby-sakila-kit/tree/with-mongodb-plugin).
+
 ## MongoDB Client
 
 You can access the underlying MongoDB client directly.
@@ -206,9 +277,9 @@ return [
 | port | `27017` | |
 | username | `null` | |
 | password | `null` | |
-| database | `kirby` |   |
-| khulan.read | `true`  | read from cache   |
-| khulan.write | `true` | write to cache   |
+| database | `kirby` | you can give it any name you want and MongoDB will create it for you |
+| khulan.read | `false` | read from cache is disabled by default as loading from file might be faster |
+| khulan.write | `true` | write to cache for all models that use the ModelWithKhulan trait |
 | khulan.patch-files-class | `true` | monkey-patch the \Kirby\CMS\Files class to use Khulan for caching it content |
 
 ## Disclaimer

classes/Mongodb.php

@@ -16,7 +16,7 @@
 
 final class Mongodb extends Cache
 {
- protected Client $_client;
+ protected ?Client $_client = null;
 
  /**
  * Sets all parameters which are needed to connect to MongoDB.
@@ -44,20 +44,7 @@ public function __construct(array $options = [])
 
  parent::__construct($this->options);
 
- if (! empty($this->options['username']) && ! empty($this->options['password'])) {
- $auth = $this->options['username'].':'.$this->options['password'].'@';
- } else {
- $auth = '';
- }
-
- $this->_client = new Client(
- 'mongodb://'.$auth.$this->options['host'].':'.$this->options['port']
- );
- $this->_client->selectDatabase($this->options['database']);
-
- if ($this->option('debug')) {
- $this->flush();
- }
+ // client init is done lazily see ->client()
  }
 
  /**
@@ -201,12 +188,29 @@ public function cache(): self
 
  public function client(): Client
  {
+ if (! $this->_client) {
+ if (! empty($this->options['username']) && ! empty($this->options['password'])) {
+ $auth = $this->options['username'].':'.$this->options['password'].'@';
+ } else {
+ $auth = '';
+ }
+
+ $this->_client = new Client(
+ 'mongodb://'.$auth.$this->options['host'].':'.$this->options['port']
+ );
+ $this->_client->selectDatabase($this->options['database']);
+
+ if ($this->option('debug')) {
+ $this->flush();
+ }
+ }
+
  return $this->_client;
  }
 
  public function collection(string $collection): Collection
  {
- return $this->_client->selectCollection($this->options['database'], $collection);
+ return $this->client()->selectCollection($this->options['database'], $collection);
  }
 
  public function cacheCollection(): Collection

composer.json

@@ -1,7 +1,7 @@
 {
  "name": "bnomei/kirby-mongodb",
  "type": "kirby-plugin",
- "version": "1.0.2",
+ "version": "1.1.0",
  "description": "Khulan is a cache driver and content cache with NoSQL interface for Kirby using MongoDB",
  "license": "MIT",
  "authors": [