add example in readme

README.md

@@ -1,11 +1,65 @@
 # rekalogika/doctrine-collections-decorator
 
-Lets you easily create decorator classes to modify the behaviors of a Doctrine
-collection.
+Lets you easily create decorator classes to dynamically modify the behaviors of
+Doctrine Collection objects, including the collection objects used by Doctrine
+ORM in your entities.
 
 ## Synopsis
 
+The decorator class extending one of our abstract classes:
+
 ```php
+use Doctrine\Common\Collections\Collection;
+use Rekalogika\Collections\Decorator\AbstractCollectionDecorator;
+
+/**
+ * @extends AbstractCollectionDecorator<array-key,Book>
+ */
+class BookCollection extends AbstractCollectionDecorator
+{
+    /**
+     * @param Collection<array-key,Book> $collection
+     */
+    public function __construct(private Collection $collection)
+    {
+    }
+
+    protected function getWrapped(): Collection
+    {
+        return $this->collection;
+    }
+
+    // add and override methods here:
+    // ...
+}
+```
+
+The usage in an entity:
+
+```php
+use Doctrine\Common\Collections\ArrayCollection;
+use Doctrine\Common\Collections\Collection;
+use Doctrine\ORM\Mapping as ORM;
+
+#[ORM\Entity()]
+class BookShelf
+{
+    /**
+     * @var Collection<array-key,Book>
+     */
+    #[ORM\OneToMany(targetEntity: Book::class)]
+    private Collection $books;
+
+    public function __construct()
+    {
+        $this->books = new ArrayCollection();
+    }
+
+    public function getBooks(): BookCollection
+    {
+        return new BookCollection($this->bookskkk);
+    }
+}
 ```
 
 ## Documentation

composer.json

@@ -1,13 +1,15 @@
 {
     "name": "rekalogika/doctrine-collections-decorator",
-    "description": "Lets you easily create decorator classes to modify the behaviors of a Doctrine collection",
+    "description": "Lets you easily create decorator classes to dynamically modify the behaviors of Doctrine Collection objects, including the collection objects used by Doctrine ORM in your entities.",
     "homepage": "https://rekalogika.dev/doctrine-collections-decorator",
     "keywords": [
         "doctrine",
         "collection",
         "decorator",
         "trait",
-        "abstract"
+        "abstract",
+        "entity",
+        "wrapper"
     ],
     "license": "MIT",
     "type": "library",

tests/Model/Book.php

@@ -0,0 +1,18 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * This file is part of rekalogika/doctrine-collections-decorator package.
+ *
+ * (c) Priyadi Iman Nurcahyo <https://rekalogika.dev>
+ *
+ * For the full copyright and license information, please view the LICENSE file
+ * that was distributed with this source code.
+ */
+
+namespace Rekalogika\Collections\Decorator\Tests\Model;
+
+class Book
+{
+}

tests/Model/TypedCollectionDecorator.php

@@ -0,0 +1,54 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * This file is part of rekalogika/doctrine-collections-decorator package.
+ *
+ * (c) Priyadi Iman Nurcahyo <https://rekalogika.dev>
+ *
+ * For the full copyright and license information, please view the LICENSE file
+ * that was distributed with this source code.
+ */
+
+namespace Rekalogika\Collections\Decorator\Tests\Model;
+
+use Doctrine\Common\Collections\Collection;
+use Rekalogika\Collections\Decorator\AbstractCollectionDecorator;
+
+/**
+ * @extends AbstractCollectionDecorator<array-key,Book>
+ */
+class TypedCollectionDecorator extends AbstractCollectionDecorator
+{
+    /**
+     * @param Collection<array-key,Book> $wrapped
+     */
+    public function __construct(private Collection $wrapped)
+    {
+    }
+
+    protected function getWrapped(): Collection
+    {
+        return $this->wrapped;
+    }
+
+    private static function ensure(mixed $book): Book
+    {
+        if (!$book instanceof Book) {
+            throw new \InvalidArgumentException('Invalid input');
+        }
+
+        return $book;
+    }
+
+    public function add(mixed $element): void
+    {
+        $this->getWrapped()->add(self::ensure($element));
+    }
+
+    public function set(string|int $key, mixed $value): void
+    {
+        $this->getWrapped()->set($key, self::ensure($value));
+    }
+}