add docs

docs/assets/github-dark-dimmed.css

@@ -0,0 +1,15 @@
+pre code.hljs{display:block;overflow-x:auto;padding:1em}code.hljs{padding:3px 5px}/*!
+  Theme: GitHub Dark Dimmed
+  Description: Dark dimmed theme as seen on github.com
+  Author: github.com
+  Maintainer: @Hirse
+  Updated: 2021-05-15
+  Modified: 2022:12:27 by @michalsn
+
+  Colors taken from GitHub's CSS
+*/.hljs{color:#adbac7 !important;background-color:#22272e !important}.hljs-doctag,.hljs-keyword,.hljs-meta .hljs-keyword,.hljs-template-tag,.hljs-template-variable,.hljs-type,.hljs-variable.language_{color:#f47067}.hljs-title,.hljs-title.class_,.hljs-title.class_.inherited__,.hljs-title.function_{color:#dcbdfb}.hljs-attr,.hljs-attribute,.hljs-literal,.hljs-meta,.hljs-number,.hljs-operator,.hljs-selector-attr,.hljs-selector-class,.hljs-selector-id,.hljs-variable{color:#6cb6ff}.hljs-meta .hljs-string,.hljs-regexp,.hljs-string{color:#96d0ff}.hljs-built_in,.hljs-symbol{color:#f69d50}.hljs-code,.hljs-comment,.hljs-formula{color:#768390}.hljs-name,.hljs-quote,.hljs-selector-pseudo,.hljs-selector-tag{color:#8ddb8c}.hljs-subst{color:#adbac7}.hljs-section{color:#316dca;font-weight:700}.hljs-bullet{color:#eac55f}.hljs-emphasis{color:#adbac7;font-style:italic}.hljs-strong{color:#adbac7;font-weight:700}.hljs-addition{color:#b4f1b4;background-color:#1b4721}.hljs-deletion{color:#ffd8d3;background-color:#78191b}
+
+[data-md-color-scheme="default"] {
+    --md-default-fg-color--lightest: #575757;
+    --md-default-fg-color--light: #959595;
+}

docs/assets/hljs.js

@@ -0,0 +1,3 @@
+document.addEventListener('DOMContentLoaded', (ev) => {
+    hljs.highlightAll();
+});

docs/basic_usage.md

@@ -0,0 +1,139 @@
+# Basic usage
+
+- [Working with model](#working-with-model)
+  - [Adding tags](#adding-tags)
+  - [Modifying tags](#modifying-tags)
+  - [Removing tags](#removing-tags)
+  - [Results with tags](#results-with-tags)
+  - [Results with certain tags only](#results-with-certain-tags-only)
+  - [Results with any tags](#results-with-any-tags)
+  - [Displaying tags](#displaying-tags)
+- [Working with Entity](#working-with-entity)
+- [Helper functions](#helper-functions)
+
+## Working with model
+
+This is how basic usage look like. It's designed to easily integrate with usual form request workflow.
+
+!!! warning
+
+    Be sure to validate your tags before saving them. You should validate things like: maximum lenght, allowed characters etc.
+    The maximum length of a single tag is 32 characters.
+
+!!! note
+
+    Very nice library that can help you managing tags on a frontend is [tagify](https://github.com/yairEO/tagify).
+    Remember that validating tags on the frontend is not enought - you need backend validation too.
+
+!!! note
+
+    Your model/table should not use the `tags` field name, as it is used exclusively by this library. Please treat the `tags` field name as **reserved**.
+
+### Adding tags
+
+```php
+model(ImageModel::class)->insert([
+    'name'   => 'sampleFile.jpeg',
+    'width'  => 100,
+    'height' => 100,
+    // this is our field with tags
+    'tags'   => 'tag1,tag2,tag3', // we can also set it as an array: ['tag1', 'tag2', 'tag3']
+]);
+```
+
+### Modifying tags
+
+```php
+model(ImageModel::class)->save([
+    'id'   => 1,
+    // this is our field with tags
+    'tags' => 'tag1,tag2', // we can also set it as an array: ['tag1', 'tag2']
+]);
+```
+
+### Removing tags
+
+```php
+model(ImageModel::class)->save([
+    'id'   => 1,
+    // this is our field with tags
+    'tags' => '', // we can also set it as an array: []
+]);
+```
+
+### Results with tags
+
+You can retrieve the results, which will include tags, using the `withTags()` method, it works with all other methods from the CodeIgniter Model.
+
+```php
+model(ImageModel::class)->withTags()->find(1);
+// or
+model(ImageModel::class)->withTags()->findAll();
+```
+
+### Results with all tags
+
+This will return a result with images that have both tags assigned.
+
+```php
+model(ImageModel::class)->withAllTags(['tag1', 'tag2'])->findAll();
+```
+
+### Results with any tags
+
+This will return a result with images that have any of these tags assigned.
+
+```php
+model(ImageModel::class)->withAnyTags(['tag1', 'tag2'])->findAll();
+```
+
+### Displaying tags
+
+When we get the tags in a result, they are available as a [Collection](https://github.com/lonnieezell/myth-collection) class.
+For this reason, tag iteration is specific:
+
+```php
+$image = model(ImageModel::class)->withTags()->find(1);
+// tags are available as a Collection
+foreach ($image->tags->items() as $tag) {
+    d($tag->name, $tag->slug);
+}
+```
+
+## Working with Entity
+
+Using `TaggableEntity` trait in our entity gives us some nice features if we want to work directly on a `tags` field.
+
+```php
+$model = model(ImageModel::class);
+$image = $model->find(1);
+// set tags
+$image->tags = ['tag1', 'tag2']
+// add a new tag
+$image->addTags(['tag3']);
+// remove tag
+$image->removeTags(['tag2']);
+// save changes with tags: tag1 and tag3
+$model->save($image);
+```
+
+## Helper functions
+
+All helper functions are available without requiring additional helper.
+
+### convert_to_tags()
+
+This function is useful, especially if you do not use entity classes, and when you want to manipulate tags manually, before writing to the database.
+
+Here is an example that shows how to add a new tag to the existing ones:
+
+```php
+$model = model(ImageModel::class);
+$image = $model->withTags()->find(1);
+// instead of writing code like this:
+$image->tags->push(new Tag(['name' => 'second tag']));
+// we can simplify it to this:
+$image->tags->push(convert_to_tags('second tag'));
+```
+
+

docs/configuration.md

@@ -0,0 +1,56 @@
+# Configuration
+
+- [Model](#model)
+- [Entity](#entity)
+
+## Model
+
+All we need to do is add `HasTags` trait to our model.
+
+!!! note
+
+    You don't need to modify `$allowedFields` array (if you use it) or your existing database schema.
+
+```php
+// app/Models/ImageModel.php
+<?php
+
+// ...
+
+use CodeIgniter\Model;
+use Michalsn\CodeIgniterTags\Traits\HasTags;
+
+class ImageModel extends Model
+{
+    use HasTags;
+
+    // ...
+
+    // Values below are only an example for ImageModel table fields
+    protected $allowedFields = ['name', 'width', 'height'];
+
+    // ...
+}
+```
+
+## Entity
+
+If your model return type is an `Entity`, then you can also add `TaggableEntity` trait to it.
+It will help you with making changes related to the tags when working directly with the entity.
+
+```php
+// app/Entities/Image.php
+<?php
+
+// ...
+
+use CodeIgniter\Entity\Entity;
+use Michalsn\CodeIgniterTags\Traits\TaggableEntity;
+
+class Image extends Entity
+{
+    use TaggableEntity;
+
+    // ...
+}
+```

docs/index.md

@@ -0,0 +1,15 @@
+# CodeIgniter Tags Documentation
+
+A library that helps you build **tags** functionality around your existing models in the CodeIgniter 4 framework.
+
+### Requirements
+
+![PHP](https://img.shields.io/badge/PHP-%5E8.1-blue)
+![CodeIgniter](https://img.shields.io/badge/CodeIgniter-%5E4.3-blue)
+
+### Table of Contents
+
+* [Installation](installation.md)
+* [Configuration](configuration.md)
+* [Basic usage](basic_usage.md)
+

docs/installation.md

@@ -0,0 +1,47 @@
+# Installation
+
+- [Composer Installation](#composer-installation)
+- [Manual Installation](#manual-installation)
+- [Database migration](#database-migration)
+
+## Composer Installation
+
+The only thing you have to do is to run this command, and you're ready to go.
+
+```console
+composer require michalsn/codeigniter-tags
+```
+
+## Manual Installation
+
+In the example below we will assume, that files from this project will be located in `app/ThirdParty/tags` directory.
+
+Download this project and then enable it by editing the `app/Config/Autoload.php` file and adding the `Michalsn\CodeIgniterTags` namespace to the `$psr4` array. You also have to add `Common.php` to the `$files` array, like in the below example:
+
+```php
+<?php
+
+// ...
+
+public $psr4 = [
+    APP_NAMESPACE => APPPATH, // For custom app namespace
+    'Config'      => APPPATH . 'Config',
+    'Michalsn\CodeIgniterTags' => APPPATH . 'ThirdParty/tags/src',
+];
+
+// ...
+
+public $files = [
+    APPPATH . 'ThirdParty/tags/src/Common.php',
+];
+```
+
+## Database migration
+
+Regardless of which installation method you chose, we also need to migrate the database to add new tables.
+
+You can do this with the following command:
+
+```console
+php spark migrate --all
+```

mkdocs.yml

@@ -0,0 +1,53 @@
+site_name: CodeIgniter Tags
+site_description: Tags library documentation for CodeIgniter 4 framework
+
+theme:
+  name: material
+  logo: assets/flame.svg
+  favicon: assets/favicon.ico
+  icon:
+    repo: fontawesome/brands/github
+  palette:
+    - media: "(prefers-color-scheme: light)"
+      scheme: default
+      primary: indigo
+      accent: indigo
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
+    - media: "(prefers-color-scheme: dark)"
+      scheme: slate
+      primary: indigo
+      accent: indigo
+      toggle:
+        icon: material/brightness-4
+        name: Switch to light mode
+
+extra:
+  homepage: https://michalsn.github.io/codeigniter-tags
+
+  social:
+    - icon: fontawesome/brands/github
+      link: https://github.com/michalsn/codeigniter-tags
+      name: GitHub
+
+repo_url: https://github.com/michalsn/codeigniter-tags
+edit_uri: edit/develop/docs/
+
+markdown_extensions:
+  - pymdownx.superfences
+  - pymdownx.highlight:
+      use_pygments: false
+
+extra_css:
+  - assets/github-dark-dimmed.css
+
+extra_javascript:
+  - https://cdn.jsdelivr.net/gh/highlightjs/cdn-release@11.6.0/build/highlight.min.js
+  - assets/hljs.js
+
+nav:
+  - Home: index.md
+  - Installation: installation.md
+  - Configuration: configuration.md
+  - Basic usage: basic_usage.md