From 03b3e02ed5aa7192ea80288995db20a466e88b41 Mon Sep 17 00:00:00 2001
From: mychidarko <mickdd22@gmail.com>
Date: Sun, 8 Dec 2024 15:28:45 +0000
Subject: [PATCH 1/8] feat: update with new mvc version docs

---
 .vitepress/config/sidebar.ts                  |  2 +-
 .vitepress/theme/components/shared/Banner.vue |  2 +-
 .vitepress/theme/index.ts                     |  6 +-
 src/docs/database/factories.md                |  8 +-
 src/docs/database/index.md                    | 74 +++++++++---------
 src/docs/database/models.md                   |  2 +-
 src/docs/http/cors.md                         | 18 +++++
 src/docs/http/headers.md                      |  2 +-
 src/docs/mvc/commands.md                      |  8 +-
 src/docs/mvc/console.md                       | 14 ++++
 src/docs/mvc/globals.md                       | 57 ++++++++++++--
 src/docs/mvc/index.md                         | 75 +++++++++++++++----
 src/docs/security/csrf.md                     | 10 ++-
 src/docs/utils/date.md                        | 52 ++++++-------
 src/docs/utils/mail/index.md                  | 44 +++++++----
 15 files changed, 262 insertions(+), 112 deletions(-)

diff --git a/.vitepress/config/sidebar.ts b/.vitepress/config/sidebar.ts
index f59fdd64..d3712ee5 100644
--- a/.vitepress/config/sidebar.ts
+++ b/.vitepress/config/sidebar.ts
@@ -161,7 +161,7 @@ const sidebar = [
       { text: 'Factories', link: '/docs/database/factories' },
       { text: 'Writing Commands', link: '/docs/mvc/commands' },
       // { text: 'Mailing', link: '/docs/utils/mail/mvc' },
-      { text: 'MVC Helpers', link: '/docs/mvc/globals' },
+      { text: 'MVC Globals', link: '/docs/mvc/globals' },
       { text: 'Custom Libraries', link: '/docs/mvc/libraries' },
       { text: 'MVC Console Tool', link: '/docs/mvc/console' },
     ],
diff --git a/.vitepress/theme/components/shared/Banner.vue b/.vitepress/theme/components/shared/Banner.vue
index 822d027c..7a8ea22e 100644
--- a/.vitepress/theme/components/shared/Banner.vue
+++ b/.vitepress/theme/components/shared/Banner.vue
@@ -31,7 +31,7 @@ const dismiss = () => {
 <template>
   <div ref="el" class="banner">
     <div class="text">
-      WARNING You're browsing the documentation for an upcoming version of Leaf. The documentation and features of this release are subject to change.
+      🎉 Leaf MVC v3.8 released. Check out the <a href="https://blog.leafphp.dev/posts/leaf-mvc-3-8" target="_blank">release post</a>
     </div>
 
     <button type="button" @click="dismiss">
diff --git a/.vitepress/theme/index.ts b/.vitepress/theme/index.ts
index 50cc18db..bf920dbb 100644
--- a/.vitepress/theme/index.ts
+++ b/.vitepress/theme/index.ts
@@ -1,4 +1,4 @@
-import { h } from 'vue';
+import { defineAsyncComponent, h } from 'vue';
 import DefaultTheme from 'vitepress/theme';
 import { VueWriter } from 'vue-writer';
 import { MotionPlugin } from '@vueuse/motion';
@@ -15,8 +15,8 @@ export default {
   },
   Layout() {
     return h(DefaultTheme.Layout, null, {
-      // 'layout-top': () =>
-      //   h(defineAsyncComponent(() => import('./components/shared/Banner.vue'))),
+      'layout-top': () =>
+        h(defineAsyncComponent(() => import('./components/shared/Banner.vue'))),
     });
   },
 };
diff --git a/src/docs/database/factories.md b/src/docs/database/factories.md
index bae0e069..fa58487a 100644
--- a/src/docs/database/factories.md
+++ b/src/docs/database/factories.md
@@ -10,7 +10,7 @@ Factories are a way to conveniently generate large amounts of database records.
 
 To create a factory, you can use the `g:factory` command. This command will create a new factory class in the `app/database/factories` directory.
 
-```bash
+```bash:no-line-numbers
 php leaf g:factory UserFactory
 ```
 
@@ -58,7 +58,7 @@ This factory class defines the attributes for the `User` model. The `definition`
 
 To use a factory to generate records, you can use the `create` method on the factory class. This method will create a new record in the database using the attributes defined in the factory.
 
-```php
+```php:no-line-numbers
 (new UserFactory)->create(20)->save();
 ```
 
@@ -92,7 +92,7 @@ This will generate 20 records in the `users` table using the attributes defined
 
 In some cases, you may not want to save the generated records to the database. You can use the `get()` method to get the generated data without saving it to the database.
 
-```php
+```php:no-line-numbers
 $users = (new UserFactory)->create(20)->get();
 ```
 
@@ -100,6 +100,6 @@ $users = (new UserFactory)->create(20)->get();
 
 You don't need to run factories manually. You can use the `db:seed` command to run your seeders, which will in turn run your factories.
 
-```bash
+```bash:no-line-numbers
 php leaf db:seed
 ```
diff --git a/src/docs/database/index.md b/src/docs/database/index.md
index 5424240b..82505342 100644
--- a/src/docs/database/index.md
+++ b/src/docs/database/index.md
@@ -49,6 +49,41 @@ Databases are essential for most applications, as they help you store and retrie
 
 :::
 
+## Leaf MVC + DB
+
+Leaf MVC comes with built-in support for models which are a way to programmatically represent resources in your database using PHP classes. For that reason, you have no real need for this module unless you want to use Leaf Auth. If you choose to use Leaf DB in your MVC application, we have already set up everything for you. All you need to do is to head over to your `.env` file and set up your database connection details. Here are a few example connections:
+
+::: code-group
+
+```txt [MySQL]
+DB_CONNECTION=mysql
+DB_HOST=127.0.0.1
+DB_PORT=3306
+DB_DATABASE=LeafMVC
+DB_USERNAME=root
+DB_PASSWORD=
+```
+
+```txt [PostgreSQL]
+DB_CONNECTION=pgsql
+DB_HOST=127.0.0.1
+DB_PORT=5432
+DB_DATABASE=LeafMVC
+DB_USERNAME=root
+DB_PASSWORD=
+```
+
+```txt [SQLite]
+DB_CONNECTION=sqlite
+DB_DATABASE=/absolute/path/to/database.sqlite
+```
+
+:::
+
+Remember to head over to `public/index.php` and uncomment the line that says `\Leaf\Database::initDb();`. This will automatically connect to your database using the details in your environment file.
+
+You can safely skip the "Connecting to a database" section.
+
 ## Connecting to a database
 
 The first step to using a database is to create a connection. It's like opening a door to the database, allowing you to interact with it. Here's how you can connect to a database using Leaf:
@@ -100,44 +135,13 @@ db()->connect([
 
 :::
 
-If you are using Leaf MVC, we have already set up everything for you. All you need to do is to head over to your `.env` file and set up your database connection details.
-
-::: code-group
-
-```txt [MySQL]
-DB_CONNECTION=mysql
-DB_HOST=127.0.0.1
-DB_PORT=3306
-DB_DATABASE=LeafMVC
-DB_USERNAME=root
-DB_PASSWORD=
-```
-
-```txt [PostgreSQL]
-DB_CONNECTION=pgsql
-DB_HOST=127.0.0.1
-DB_PORT=5432
-DB_DATABASE=LeafMVC
-DB_USERNAME=root
-DB_PASSWORD=
-```
-
-```txt [SQLite]
-DB_CONNECTION=sqlite
-DB_DATABASE=/absolute/path/to/database.sqlite
-```
-
-:::
-
-Remember to head over to `public/index.php` and uncomment the line that says `\Leaf\Database::initDb();`. This will automatically connect to your database using the details in your environment file.
-
 ## Writing simple queries
 
 Once you've connected to a database, you can start writing queries to interact with it. Queries are the commands you run on your database to get, insert, update or delete data. Leaf DB provides a simple way to run queries using the query builder, but also allows you to run raw SQL queries.
 
 We can run queries using the `query()` method. This method takes in a query string and returns a query builder instance. This means that you can run queries like this:
 
-```php
+```php:no-line-numbers
 $users = db()->query('SELECT * FROM users')->all();
 ```
 
@@ -158,13 +162,13 @@ There are different kinds of database commands: some give you results (like data
 
 You can use `execute()` to run queries that don't return values. This method returns `true` if the query was successful and `false` if it wasn't. You can run a query like this:
 
-```php
+```php:no-line-numbers
 db()->query('CREATE DATABASE dbname')->execute();
 ```
 
 If you want to run a query that returns data, you can use the `all()` method to get all the results. For example, you can run a query like this:
 
-```php
+```php:no-line-numbers
 $users = db()->query('SELECT * FROM users')->all();
 ```
 
@@ -183,6 +187,6 @@ This will return the matched user as an object.
 
 There may be times when you want to get a single value from a query that returns multiple rows. In such cases, you can use the `first()` method. For example, you can run a query like this:
 
-```php
+```php:no-line-numbers
 $user = db()->query('SELECT * FROM users')->first();
 ```
diff --git a/src/docs/database/models.md b/src/docs/database/models.md
index 6011c5f0..8fe73006 100644
--- a/src/docs/database/models.md
+++ b/src/docs/database/models.md
@@ -51,7 +51,7 @@ This code will retrieve all rows from the `flights` table and then loop through
 
 The Leaf all method will return all of the results in the model's table. Since each Leaf model serves as a query builder, you may also add constraints to queries, and then use the get method to retrieve the results:
 
-```php
+```php:no-line-numbers
 $flights = Flight::where('active', 1)->orderBy('name', 'desc')->take(10)->get();
 ```
 
diff --git a/src/docs/http/cors.md b/src/docs/http/cors.md
index 15d2cf57..2d23ae66 100644
--- a/src/docs/http/cors.md
+++ b/src/docs/http/cors.md
@@ -79,6 +79,24 @@ app()->cors([
 
 This will allow `http://example.com`, `https://example.com`, `http://www.example.com`, and `https://some-subdomain.example.com` to access your app. Of course, you can also use a regular expression to match multiple domains. You can find a full list of options below.
 
+## CORS + Leaf MVC
+
+If you are using Leaf MVC, you can configure CORS using your environment variables in place of the configuration above:
+
+```txt:no-line-numbers [.env]
+CORS_ALLOWED_ORIGINS='/\.example\.com$/'
+CORS_ALLOWED_METHODS='GET,HEAD,PUT,PATCH,POST,DELETE'
+CORS_ALLOWED_HEADERS='*'
+```
+
+While this is easier and allows you to easily configure different environments, it can sometimes be limiting for example when you want to return a function for dynamically set your allowed origins. For this reason, you can publish your CORS configuration using the command below:
+
+```bash:no-line-numbers
+php leaf config:publish cors
+```
+
+This will create or update your CORS config in `config/cors.php`. You can then use the options below to configure the CORS module to suit your exact needs.
+
 ## Configuration Options
 
 The `cors()` method takes in an array of options. Here are the available options:
diff --git a/src/docs/http/headers.md b/src/docs/http/headers.md
index 5c3eba65..5b0858f8 100644
--- a/src/docs/http/headers.md
+++ b/src/docs/http/headers.md
@@ -122,7 +122,7 @@ Leaf\Http\Headers::remove(['WWW-Authenticate', 'Authorization']);
 
 You can check if a header exists using the `Leaf\Http\Headers::has()` method. This method takes in a single parameter, the header to check and returns a boolean.
 
-```php
+```php:no-line-numbers
 $exists = Leaf\Http\Headers::has('Content-Type');
 ```
 
diff --git a/src/docs/mvc/commands.md b/src/docs/mvc/commands.md
index e13a3fc3..50ed38c3 100644
--- a/src/docs/mvc/commands.md
+++ b/src/docs/mvc/commands.md
@@ -82,7 +82,7 @@ class CachePurgeCommand extends Command
 }
 ```
 
-If you are using Leaf MVC v3.8 and above, the command is automatically loaded by Leaf MVC. If you are using Leaf MVC v3.7 and below, you will need to register the command in the `app/console/Commands.php` file.n
+If you are using Leaf MVC v3.8 and above, the command is automatically loaded by Leaf MVC. If you are using Leaf MVC v3.7 and below, you will need to register the command in the `app/console/Commands.php` file.
 
 ```php
 <?php
@@ -112,7 +112,7 @@ class Commands
 
 Command arguments are values that are passed to the command when it is run in the console. For example, if you have a command named `example` and you run it like this:
 
-```bash
+```bash:no-line-numbers
 php leaf example argument
 ```
 
@@ -138,7 +138,7 @@ protected function handle()
 
 Command options are values that are passed to the command when it is run in the console. For example, if you have a command named `example` and you run it like this:
 
-```bash
+```bash:no-line-numbers
 php leaf example --option=value
 ```
 
@@ -371,6 +371,6 @@ This method asks a question but hides the keystrokes. It takes in 2 parameters:
 - the question to ask
 - use hidden fallback (optional)
 
-```php
+```php:no-line-numbers
 $password = $this->secret('Confirm your password');
 ```
diff --git a/src/docs/mvc/console.md b/src/docs/mvc/console.md
index 4f87b9f5..42f8c145 100644
--- a/src/docs/mvc/console.md
+++ b/src/docs/mvc/console.md
@@ -8,6 +8,20 @@ Leaf MVC includes a powerful command-line tool called Aloe to help you manage yo
 php leaf list
 ```
 
+::: details Missing commands?
+
+If you get errors from commands which you saw in the documentation, you are probably running an older version of the Leaf MVC console. We add more handy commands regularly, but as the console does not automatically update, you may run into the missing command error. To fix that problem, you need to install the latest version of Aloe:
+
+```bash:no-line-numbers
+leaf install aloe
+
+# or with composer
+
+composer require leafs/aloe
+```
+
+:::
+
 ## Aloe vs. Leaf CLI: What's the Difference?
 
 Before diving in, it’s important to know that Aloe is different from Leaf CLI.
diff --git a/src/docs/mvc/globals.md b/src/docs/mvc/globals.md
index d40c8a5f..df88e57f 100644
--- a/src/docs/mvc/globals.md
+++ b/src/docs/mvc/globals.md
@@ -17,12 +17,59 @@ $controllersPath = AppPaths('controllers'); // you can do this
 $controllersPath = $paths['controllers']; // or this
 ```
 
-If the path you are looking for doesn't have a helper function, you can use the `AppPaths()` helper to get the path. Just make sure that the path is defined in your `config/paths.php` file.
+If the path you are looking for doesn't have a helper function, you can use the `AppPaths()` helper to get the path. Just make sure that the path is defined in your `config/paths.php` file. If your Leaf MVC app does not come with a `config/paths.php` file, you can create one. This is the default structure of the `config/paths.php` file:
+
+```php{15}
+<?php
+
+/*
+|--------------------------------------------------------------------------
+| Paths Config
+|--------------------------------------------------------------------------
+|
+| Leaf allows you to completely modify the directory structure of your
+| MVC application. This file just tells Leaf and other components
+| where to find the important files in your app.
+|
+*/
+
+return [
+    'myCustomPath' => 'app/myCustomPath',
+    'commands' => 'app/console',
+    'config' => 'config',
+    'channels' => 'app/channels',
+    'components' => 'app/components',
+    'controllers' => 'app/controllers',
+    'databaseStorage' => 'storage/app/db',
+    'events' => 'app/events',
+    'factories' => 'app/database/factories',
+    'helpers' => 'app/helpers',
+    'jobs' => 'app/jobs',
+    'lib' => 'lib',
+    'mail' => 'app/mail',
+    'middleware' => 'app/middleware',
+    'migrations' => 'app/database/migrations',
+    'models' => 'app/models',
+    'routes' => 'app/routes',
+    'schema' => 'app/database/schema',
+    'scripts' => 'app/scripts',
+    'seeds' => 'app/database/seeds',
+    'services' => 'app/services',
+    'storage' => 'storage',
+    'utils' => 'app/utils',
+    'views' => 'app/views',
+    'workers' => 'app/workers',
+];
+```
 
-```php
-AppPaths('weirdPath');
+After defining your paths in your `config/paths.php` file, you can use the `AppPaths()` helper to get the path.
+
+```php:no-line-numbers
+AppPaths('myCustomPath');
 ```
 
+Keep in mind that not every path in your `config/paths.php` file has a helper function. If you want to get the path to a path that doesn't have a helper function, you can use the `AppPaths()` helper.
+
 ### assets()
 
 This returns the path to your assets folder. You can pass in a file name to get the path to that file.
@@ -34,7 +81,7 @@ $asset = assets('css/main.css');
 
 You can configure the path to your assets folder in your `config/paths.php` file.
 
-```php
+```php:no-line-numbers
 'assets' => 'public/assets'
 ```
 
@@ -53,7 +100,7 @@ This returns the path to your commands folder. You can pass in a file name to ge
 
 ```php
 $command = CommandsPath('MainCommand.php');
-// -> app/commands/MainCommand.php
+// -> app/console/MainCommand.php
 ```
 
 ### ControllersPath()
diff --git a/src/docs/mvc/index.md b/src/docs/mvc/index.md
index 96763b7d..72ffb01b 100644
--- a/src/docs/mvc/index.md
+++ b/src/docs/mvc/index.md
@@ -13,7 +13,7 @@ Leaf is a lightweight PHP framework with a ton of loosely coupled libraries that
 MVC stands for Model-View-Controller. It is a pattern that separates your application into three distinct parts:
 
 - Models: These are the classes that represent your data. They are responsible for interacting with your database, and for validating your data.
-- Views: These are the files that are responsible for displaying your data to your user. They are usually written in HTML, but can also be written in other templating languages like [BareUI](https://leafphp.dev/docs/views/bareui/) or [Blade](https://leafphp.dev/docs/views/blade/) or frameworks like [Vue](https://vuejs.org/) or [React](https://reactjs.org/)
+- Views: These are the files that are responsible for displaying your data to your user. They are usually written in HTML, but can also be written in other templating languages like [BareUI](/docs/frontend/bareui/) or [Blade](/docs/frontend/blade/) or frameworks like [Vue](https://vuejs.org/) or [React](https://reactjs.org/)
 - Controllers: These are the classes that are responsible for handling the user's request, and for returning the appropriate response.
 
 ::: details New to MVC?
@@ -27,9 +27,9 @@ If you're new to the MVC pattern, you can take a look at this video by Traversy
 
 ## MVC in Leaf
 
-Leaf provides a minimal but powerful setup for building applications using the MVC pattern. It's built on top of Leaf, and comes with additional tooling that makes building with Leaf even faster. It is a good starting point for building applications using the MVC pattern.
+Leaf provides a minimal but powerful setup for building applications using the MVC pattern. It's built on top of Leaf, and comes with additional tooling that makes building with Leaf even faster. It is a good starting point for building scalable applications with well-organized code.
 
-## Installation
+### Installation
 
 You can set up a new MVC application using the [Leaf CLI](/docs/cli/) or using [Composer](https://getcomposer.org/). They both work, but using the Leaf CLI gives you the option to choose between a regular MVC app and an MVC app that is fine-tuned for creating APIs, plus a few other options.
 
@@ -49,21 +49,41 @@ This command will set up a new MVC app in the `<project-name>` directory. You ca
 
 ```bash:no-line-numbers
 cd <project-name>
-leaf serve # or php leaf serve
+php leaf serve
 ```
 
 You should then see the welcome page in your browser.
 
-![Leaf MVC Welcome Page](https://user-images.githubusercontent.com/26604242/223189921-d5da1555-bc29-4f99-a3ec-d6cbfdc5350b.png)
+![Leaf MVC Welcome Page](https://github.com/user-attachments/assets/947cc13e-cada-4489-aed4-b3f44b262b76)
 
 ## Directory Structure
 
-The Leaf MVC directory structure is inspired by [Ruby on Rails](https://rubyonrails.org/) and [Laravel](https://laravel.com/). It takes a lot of inspiration from these frameworks, but it's not a clone of either of them. It is meant to be a starting point for building your own applications, and is fully customizable. You can completely change the directory structure to suit your needs, just be sure to update the paths in the `config/paths.php` file.
+The Leaf MVC directory structure is inspired by [Ruby on Rails](https://rubyonrails.org/) and [Laravel](https://laravel.com/). It takes a lot of inspiration from these frameworks, but it's not a clone of either of them. It is meant to be a starting point for building your own applications, and is fully customizable. You can completely change the directory structure to suit your needs, just be sure to update the [paths config file](/docs/mvc/globals.html#loading-app-paths).
 
 For a fresh MVC app, the directory structure looks like this:
 
-```bash:no-line-numbers
-.
+::: code-group
+
+```bash:no-line-numbers [v3.8 upwards]
+├───app
+│   ├── controllers
+│   ├── database
+│   │   ├── factories
+│   │   ├── migrations
+│   │   ├── schema
+│   │   └── seeds
+│   ├── models
+│   ├── routes
+│   └── views
+│       └── errors
+├───public
+│   └───assets
+│       ├── css
+│       └── img
+└───vendor
+```
+
+```bash:no-line-numbers [v3.7 downwards]
 ├───app
 │   ├── console
 │   ├── controllers
@@ -91,11 +111,13 @@ For a fresh MVC app, the directory structure looks like this:
 └───vendor
 ```
 
+:::
+
 - ### The `app` directory
 
   The `app` directory contains the core code of your application. It's divided into a few sub-directories:
 
-  - `console` - Contains the console commands for your application. These are used to perform tasks on the command line.
+  - `console` - Contains the console commands for your application. These are used to perform tasks on the command line. You can check the [console commands](/docs/mvc/commands) documentation for more information.
   - `controllers` - Contains the controllers for your application. These are used to handle HTTP requests.
   - `database` - Contains the database related code for your application. This includes migrations, seeds, factories and schema.
   - `helpers` - Contains the helper functions for your application.
@@ -105,7 +127,9 @@ For a fresh MVC app, the directory structure looks like this:
 
 - ### The `config` directory
 
-  The `config` directory contains the configuration files for your application. These are used to configure how Leaf and it's modules interact with your application. Each file controls a different feature of your application, e.g. the `app.php` file is used to configure the application, the `database.php` file is used to configure the database connection, etc.
+  The `config` directory contains the configuration files for your application. v3.8 and above do not come with a `config` directory out of the box, but you can publish the default configuration files using the [`config:publish` command](#configuring-leaf-mvc).
+
+  The configuration files are used to configure how Leaf and it's modules interact with your application. Each file controls a different feature of your application, e.g. the `app.php` file is used to configure the application, the `database.php` file is used to configure the database connection, etc.
 
 - ### The `public` directory
 
@@ -127,13 +151,36 @@ For a fresh MVC app, the directory structure looks like this:
 
 ## Configuring Leaf MVC
 
-Leaf MVC tries to maintain a clean and easy-to-understand structure that works out-of-the-box for most applications. However, there are times when you need to customize some features to fit your specific use-cases.
+Leaf MVC tries to maintain a clean and easy-to-understand structure that works out-of-the-box for most applications, which means that for most applications, you only need to change a few details in your .env file. For this reason, we don't ship with a `config` directory by default.
+
+There are however some times when you need to customize some features to fit your specific use-cases, and that's where the configuration files come in. Leaf MVC separates the configuration files for each feature of the framework, so you can easily customize one feature without affecting the others. To publish all the default configuration files, you can run the following command:
+
+```bash:no-line-numbers
+php leaf config:publish
+```
+
+This will create a config directory in your application root and copy all the default configuration files to this directory just as we had in previous versions. You can then go ahead to customize the configuration files to fit your specific use-cases.
+
+Since Leaf MVC has defaults set for most of the configuration options, you don't need to change all the values in the configuration files, you only need to change only the specific values you want to customize so you can leave the rest of the configuration as it is. Each option is documented, so feel free to look through the files and get familiar with the options available to you.
 
-You can find all the configuration options used by Leaf MVC in the `config` directory of your Leaf MVC project. Each feature has its own configuration file, and you can customize these files to fit your needs, e.g. the database configuration file is `config/database.php`.
+If you have a specific configuration you want to change, you can publish only that configuration file by running the following command:
 
-You only need to change only the specific values you want to customize so you can leave the rest of the configuration as it is. Each option is documented, so feel free to look through the files and get familiar with the options available to you.
+```bash:no-line-numbers
+php leaf config:publish <config-file>
+```
 
-For the final bit, we hooked up most of the configuration files to your `.env` file so you can easily change your configuration values without having to touch the configuration files directly. This is especially useful when you want to deploy your application to different environments.
+This will copy the specified configuration file to the `config` directory in your application root, and you can then go ahead to customize the configuration file to fit your specific use-case. This is a list of all of Leaf MVC's configuration files:
+
+| Config file       |  Use-case                                                     |
+| ----------------- | :------------------------------------------------------------ |
+| app               | Configuration for core features                               |
+| auth              | Configuration for authentication (requires auth module)       |
+| cors              | Configuration for cors (requires cors module)                 |
+| csrf              | Configuration for csrf protection (requires csrf module)      |
+| database          | Configuration for database stuff                              |
+| mail              | Configuration for mailing (requires mail module)              |
+| redis             | Configuration for redis management (requires redis module)    |
+| view              | Configuration for view rendering                              |
 
 ## Application Environment
 
diff --git a/src/docs/security/csrf.md b/src/docs/security/csrf.md
index 40cdbb12..cc55374e 100644
--- a/src/docs/security/csrf.md
+++ b/src/docs/security/csrf.md
@@ -62,9 +62,15 @@ This will automatically generate a CSRF token using a default secret key and a r
 
 If the CSRF token is missing or invalid, the CSRF module will throw an exception, which you can catch and handle as you see fit.
 
-::: info Leaf MVC + CSRF
+::: info Usage with Leaf MVC
 
-Once you install the CSRF module, Leaf will automatically pick up the `config/csrf.php` file and use it to set up CSRF protection for your app, so you don't need to manually call `app()->csrf()` or worry about passing any configuration to the CSRF module.
+After installing the CSRF module, Leaf will automatically configure it and initialize it on all POST, PUT, PATCH and DELETE requests. If you want to configure the CSRF module manually, you can run the command below:
+
+```bash:no-line-numbers
+php leaf config:publish csrf
+```
+
+This will generate or update your CSRF config in the `config/csrf.php` file. Any changes you make in this file will be automatically applied to the CSRF module.
 
 :::
 
diff --git a/src/docs/utils/date.md b/src/docs/utils/date.md
index b52d3816..ebed4f49 100644
--- a/src/docs/utils/date.md
+++ b/src/docs/utils/date.md
@@ -4,7 +4,7 @@ Working with PHP dates can be challenging due to various date formats, handling
 
 Leaf provides a minimalistic module that provides a simple and clean API for working with dates in PHP. It is 100% compatible with PHP's native `DateTime` class, but offers a more fluent and expressive API inspired by Day.js.
 
-```php
+```php:no-line-numbers
 tick()->now(); // get the current timestamp
 tick()->format('YYYY-MM-DD'); // format the current timestamp
 tick()
@@ -36,7 +36,7 @@ Once installed, you can start using Tick in your application.
 
 You probably noticed the `tick()` function in the examples above. This function is the entry point for Tick and initializes a date for manipulation or formatting. You can pass a date string, a timestamp, or a `DateTime` object to the `tick()` function.
 
-```php
+```php:no-line-numbers
 tick(); // will use today's date
 tick('2018-01-01 12:00:00'); // create a date from a string
 
@@ -50,14 +50,14 @@ Tick is versatile and smart enough to handle dates correctly, so you can pass in
 
 Tick provides methods for getting and setting various parts of a date, such as the year, month, day, hour, minute, second, and millisecond. This uses a syntax where the same function can be used to get or set a value.
 
-```php
+```php:no-line-numbers
 tick()->second(30); // set the second to 30
 tick()->second(); // get the second
 ```
 
 This works for all parts of a date, including the year, month, day, hour, minute, second, and millisecond.
 
-```php
+```php:no-line-numbers
 tick()->year(2018); // set the year to 2018
 tick()->year(); // get the year
 
@@ -85,7 +85,7 @@ tick()->millisecond(1); // returns new tick object
 
 You can also use the `get()` and `set()` methods to get and set values.
 
-```php
+```php:no-line-numbers
 tick()->get('year'); // get the year
 tick()->set('year', 2018); // set the year to 2018
 ```
@@ -110,7 +110,7 @@ This is a fancy way of saying "changing dates" into some other kind of date. Tic
 
 *All manipulation methods return a new Tick object, so you can chain them together.*
 
-```php
+```php:no-line-numbers
 tick()->add(1, 'day')->format('YYYY-MM-DD');
 ```
 
@@ -118,14 +118,14 @@ tick()->add(1, 'day')->format('YYYY-MM-DD');
 
 Tick allows you to add time to a date using the `add()` method. You can add any number of years, months, days, hours, minutes, seconds, or milliseconds to a date.
 
-```php
+```php:no-line-numbers
 tick()->add(1, 'day');
 tick()->add(1, 'week');
 ```
 
 You can also subtract time from a date using the `subtract()` method.
 
-```php
+```php:no-line-numbers
 tick()->subtract(1, 'day');
 tick()->subtract(1, 'week');
 ```
@@ -147,14 +147,14 @@ This is a list of all available units that can be used with the `add()` and `sub
 
 You can get the start of a unit using the `startOf()` method. This method sets the date to the start of the specified unit, such as the start of the day, month, or year. For example, to get the first day of the month or the first day of the year, you can use the following code:
 
-```php
+```php:no-line-numbers
 tick()->startOf('month'); // => 2024-10-01 00:00:00
 tick()->startOf('year'); // => 2024-01-01 00:00:00
 ```
 
 You can also use the `endOf()` method to get the end of a unit. This method sets the date to the end of the specified unit, such as the end of the day, month, or year. For example, to get the last day of the month or the last day of the year, you can use the following code:
 
-```php
+```php:no-line-numbers
 tick()->endOf('month'); // => 2024-10-31 23:59:59
 tick()->endOf('year'); // => 2024-12-31 23:59:59
 ```
@@ -178,7 +178,7 @@ The following units are available for use with the `startOf()` and `endOf()` met
 
 Formatting dates is a common task when working with dates in PHP. Formatting a date allows you to display the date in a specific format, such as `YYYY-MM-DD` or `DD/MM/YYYY`. Tick provides a `format()` method that allows you to format a date using a format string.
 
-```php
+```php:no-line-numbers
 tick()->format();
 // '2024-10-03T18:04:37+00:00'
 // current date in ISO8601, without fraction seconds
@@ -218,7 +218,7 @@ You can combine various format tokens to create a custom date format. The follow
 
 Anything you pass into the `format()` method will be formatted according to the format string you provide. If you want to ignore parts of information you pass into the `format()` method, you can wrap them in square brackets.
 
-```php
+```php:no-line-numbers
 tick('2019-01-25')->format('[YYYYescape] YYYY-MM-DDTHH:mm:ssZ[Z]');
 // 'YYYYescape 2019-01-25T00:00:000Z'
 ```
@@ -229,14 +229,14 @@ YYYYescape got ignored instead of turning into a year. This is powerful, especia
 
 You can get how far a date is from now using the `fromNow()` method. This method returns a string that represents the difference between the date and the current date in a human-readable format.
 
-```php
+```php:no-line-numbers
 tick('2014-10-01')->fromNow(); // 10 years ago
 tick('2027-10-04')->fromNow(); // in 3 years
 ```
 
 If you want to remove the suffix (ago or in), you can pass `true` as the first argument to the `fromNow()` method.
 
-```php
+```php:no-line-numbers
 tick('2014-10-01')->fromNow(true); // 10 years
 tick('2027-10-04')->fromNow(true); // 3 years
 ```
@@ -245,14 +245,14 @@ tick('2027-10-04')->fromNow(true); // 3 years
 
 If you want to check how much time has passed since a specific date, you can use the `from()` method. This method returns a string that represents the difference between the date and the specified date in a human-readable format.
 
-```php
+```php:no-line-numbers
 tick('2014-10-01')->from('2015-10-01'); // 1 year ago
 tick('2015-10-01')->from('2014-10-01'); // in 1 year
 ```
 
 If you want to remove the suffix (ago or in), you can pass `true` as the first argument to the `from()` method.
 
-```php
+```php:no-line-numbers
 tick('2014-10-01')->from('2015-10-01', true); // 1 year
 tick('2015-10-01')->from('2014-10-01', true); // 1 year
 ```
@@ -265,7 +265,7 @@ Querying dates allows you to check relationships between dates, such as whether
 
 This indicates whether the Tick object is before the other supplied date-time.
 
-```php
+```php:no-line-numbers
 tick()->isBefore('2011-01-01');
 ```
 
@@ -273,7 +273,7 @@ tick()->isBefore('2011-01-01');
 
 This indicates whether the Tick object is the same as the other supplied date-time.
 
-```php
+```php:no-line-numbers
 tick()->isSame(new \DateTime('2011-01-01'));
 ```
 
@@ -281,7 +281,7 @@ tick()->isSame(new \DateTime('2011-01-01'));
 
 This indicates whether the Tick object is after the other supplied date-time.
 
-```php
+```php:no-line-numbers
 tick()->isAfter('2011-01-01');
 ```
 
@@ -289,7 +289,7 @@ tick()->isAfter('2011-01-01');
 
 This indicates whether the Tick object is between two other supplied date-time.
 
-```php
+```php:no-line-numbers
 tick('2010-10-20')
   ->isBetween('2010-10-19', new \DateTime('2010-10-25'));
 ```
@@ -298,7 +298,7 @@ tick('2010-10-20')
 
 This indicates whether the Tick object is between two other supplied date-time or equal to one of them.
 
-```php
+```php:no-line-numbers
 tick('2010-10-20')
   ->isBetweenOrEqual('2010-10-19', new \DateTime('2010-10-25'));
 ```
@@ -307,7 +307,7 @@ tick('2010-10-20')
 
 This indicates whether the Tick object is the same day as the other supplied date-time.
 
-```php
+```php:no-line-numbers
 tick('2010-10-20')->isSameDay('2010-10-20');
 ```
 
@@ -315,7 +315,7 @@ tick('2010-10-20')->isSameDay('2010-10-20');
 
 This indicates whether the Tick object is the same month as the other supplied date-time.
 
-```php
+```php:no-line-numbers
 
 
 tick('2010-10-20')->isSameMonth('2010-10-20');
@@ -325,7 +325,7 @@ tick('2010-10-20')->isSameMonth('2010-10-20');
 
 This indicates whether the Tick object is the same year as the other supplied date-time.
 
-```php
+```php:no-line-numbers
 tick('2010-10-20')->isSameYear('2010-10-20');
 ```
 
@@ -333,7 +333,7 @@ tick('2010-10-20')->isSameYear('2010-10-20');
 
 This indicates whether the Tick object's year is a leap year or not.
 
-```php
+```php:no-line-numbers
 tick('2000-01-01')->isLeapYear(); // true
 ```
 
@@ -341,6 +341,6 @@ tick('2000-01-01')->isLeapYear(); // true
 
 This indicates whether the Tick object is a DateTime object or not.
 
-```php
+```php:no-line-numbers
 tick()->isDateTime('2000-01-01'); // false
 ```
diff --git a/src/docs/utils/mail/index.md b/src/docs/utils/mail/index.md
index ed30aa09..3dc67271 100644
--- a/src/docs/utils/mail/index.md
+++ b/src/docs/utils/mail/index.md
@@ -39,17 +39,7 @@ Once you've installed Leaf Mail, you need to connect to your mail server. Every
 
 Since every mail server is different, you'll need to check your mail server's documentation for the correct configuration options.
 
-## Connection in Leaf MVC
-
-If you're using Leaf MVC, we've included a handy command that sets up mailing in your application:
-
-```bash:no-line-numbers
-php leaf config:mail
-```
-
-This command will create a `config/mail.php` file which contains all the configuration options for your mail server. The configuration options are the same as the ones we listed above and you can use them to configure your mail server connection.
-
-You can refer to the examples below for how to connect to different mail servers. Just remember to exclude the `mailer()->connect()` section as that is already done for you.
+::: details Example connections
 
 ## Example SMTP connection
 
@@ -75,8 +65,6 @@ mailer()->connect([
 
 Below is an example of connecting to a Gmail server. This example uses OAuth, which is the only way to connect to Gmail servers:
 
-::: code-group
-
 ```bash:no-line-numbers [Leaf CLI]
 leaf install league/oauth2-google
 ```
@@ -85,8 +73,6 @@ leaf install league/oauth2-google
 composer require league/oauth2-google
 ```
 
-:::
-
 We install the `league/oauth2-google` package to handle the OAuth connection to Gmail. This is how the connection to Gmail would look:
 
 ```php
@@ -115,6 +101,34 @@ mailer()->connect([
 ]);
 ```
 
+:::
+
+## Connection in Leaf MVC
+
+If you're using Leaf MVC, the simplest way to connect to your mail server is to use your .env file. You can update the following configuration options in your .env file:
+
+```txt
+MAIL_HOST=sandbox.smtp.mailtrap.io
+MAIL_PORT=2525
+MAIL_USERNAME=xxx
+MAIL_PASSWORD=xxx
+MAIL_DEBUG=SERVER
+MAIL_SENDER_NAME='Leaf MVC'
+MAIL_SENDER_EMAIL=user@example.com
+```
+
+That's it! Leaf Mail will automatically connect to your mail server when you send an email.
+
+While this is a simple and straightforward way to connect to your mail server, you may need finer control over your mail server connection, for example, you may want to connect to a server that only supports OAuth. In this case, you can publish the mail configuration file from Leaf MVC using the following command:
+
+```bash:no-line-numbers
+php leaf config:publish mail
+```
+
+This command will create a `config/mail.php` file which contains all the configuration options for your mail server. The configuration options are the same as the ones we listed above and will still be linked to the correct environment variables, so you can still use your .env file to configure your mail server.
+
+You can refer to the examples above for how to connect to different mail servers. Just remember to exclude the `mailer()->connect()` section as that is already done for you.
+
 ## Writing mails
 
 Once we have all the annoying stuff out of the way, we can now write our emails. This involves creating a new mail and then sending it when you're ready. At it's core, a mail is just a class call to the `mail()->create()` method. This method takes in the name of the mail you want to create and returns a new mail object.

From a7bc6c241f1090ffed848863086c06f063729243 Mon Sep 17 00:00:00 2001
From: mychidarko <mickdd22@gmail.com>
Date: Fri, 13 Dec 2024 10:03:06 +0000
Subject: [PATCH 2/8] feat: update mvc docs

---
 src/docs/mvc/index.md | 11 +++++++----
 1 file changed, 7 insertions(+), 4 deletions(-)

diff --git a/src/docs/mvc/index.md b/src/docs/mvc/index.md
index 72ffb01b..32b3c1c2 100644
--- a/src/docs/mvc/index.md
+++ b/src/docs/mvc/index.md
@@ -76,6 +76,7 @@ For a fresh MVC app, the directory structure looks like this:
 │   ├── routes
 │   └── views
 │       └── errors
+├───config
 ├───public
 │   └───assets
 │       ├── css
@@ -127,9 +128,9 @@ For a fresh MVC app, the directory structure looks like this:
 
 - ### The `config` directory
 
-  The `config` directory contains the configuration files for your application. v3.8 and above do not come with a `config` directory out of the box, but you can publish the default configuration files using the [`config:publish` command](#configuring-leaf-mvc).
+  The `config` directory contains the configuration files for your application. The configuration files are used to configure how Leaf and it's modules interact with your application. Each file controls a different feature of your application, e.g. the `app.php` file is used to configure the application, the `database.php` file is used to configure the database connection, etc.
 
-  The configuration files are used to configure how Leaf and it's modules interact with your application. Each file controls a different feature of your application, e.g. the `app.php` file is used to configure the application, the `database.php` file is used to configure the database connection, etc.
+  Leaf MVC now allows you to completely remove this directory if you are only going to use the default configuration values which will make your application lighter. Leaf v3.8 and above allow you to publish the default configuration files using the [`config:publish` command](#configuring-leaf-mvc) if you end up deleting the `config` directory and want it back.
 
 - ### The `public` directory
 
@@ -145,13 +146,15 @@ For a fresh MVC app, the directory structure looks like this:
   - `framework` - Contains the framework generated files for your application.
   - `logs` - Contains the log files generated by your application.
 
+  This directory is not created by default in Leaf v3.8 and above. It will be automatically created when you run the `leaf serve` command, logging, storage link or any other command/module that requires it.
+
 - ### The `vendor` directory
 
   The `vendor` directory contains all the dependencies installed by Composer. It's automatically generated when you install the dependencies using Composer.
 
 ## Configuring Leaf MVC
 
-Leaf MVC tries to maintain a clean and easy-to-understand structure that works out-of-the-box for most applications, which means that for most applications, you only need to change a few details in your .env file. For this reason, we don't ship with a `config` directory by default.
+Leaf MVC tries to maintain a clean and easy-to-understand structure that works out-of-the-box for most applications, which means that for most applications, you only need to change a few details in your .env file. For this reason, we allow you to completely remove the `config` directory if you are only going to use the default configuration values. This will make your application lighter and easier to maintain.
 
 There are however some times when you need to customize some features to fit your specific use-cases, and that's where the configuration files come in. Leaf MVC separates the configuration files for each feature of the framework, so you can easily customize one feature without affecting the others. To publish all the default configuration files, you can run the following command:
 
@@ -159,7 +162,7 @@ There are however some times when you need to customize some features to fit you
 php leaf config:publish
 ```
 
-This will create a config directory in your application root and copy all the default configuration files to this directory just as we had in previous versions. You can then go ahead to customize the configuration files to fit your specific use-cases.
+This will re-create a config directory in your application root and copy all the default configuration files to this directory just as we had in previous versions. You can then go ahead to customize the configuration files to fit your specific use-cases.
 
 Since Leaf MVC has defaults set for most of the configuration options, you don't need to change all the values in the configuration files, you only need to change only the specific values you want to customize so you can leave the rest of the configuration as it is. Each option is documented, so feel free to look through the files and get familiar with the options available to you.
 

From c21f406d3034369fc76df929d19954bfd345a63d Mon Sep 17 00:00:00 2001
From: mychidarko <mickdd22@gmail.com>
Date: Sun, 15 Dec 2024 17:44:14 +0000
Subject: [PATCH 3/8] feat: update auth middleware docs

---
 src/docs/auth/protected-routes.md | 42 +++++++++++++++++--------------
 1 file changed, 23 insertions(+), 19 deletions(-)

diff --git a/src/docs/auth/protected-routes.md b/src/docs/auth/protected-routes.md
index 8eb48f55..7ee0645b 100644
--- a/src/docs/auth/protected-routes.md
+++ b/src/docs/auth/protected-routes.md
@@ -73,15 +73,7 @@ app()->get('/protected', function () {
 
 ## Using Middleware
 
-Leaf Auth also provides a middleware that you can use to protect your routes. The `auth` middleware checks if a user is logged in and allows you to set a callback function to run if a user is not logged in.
-
-```php
-auth()->middleware('auth.required', function () {
-  response()->redirect('/login');
-});
-```
-
-Once you have defined a callback for the middleware, you can use it in your routes like this:
+Leaf Auth provides middleware to keep guest users out and logged in users in. This is a more flexible way to protect your routes and allows you to define more complex authentication logic. The `auth:required` middleware checks if a user is logged in and redirects to `/auth/login` if a user is not logged in.
 
 ```php
 app()->get('/protected', ['middleware' => 'auth.required', function () {
@@ -96,35 +88,47 @@ app()->group('/protected', ['middleware' => 'auth.required', function () {
 }]);
 ```
 
-If you use this method, the middleware will run before the route is executed. If the user is not logged in, the callback function you defined will be executed. This means you can remove the check for a logged in user from your route handler.
+The route or group of routes will only be accessible to logged in users, so you don't need to check if a user is logged in inside the route handler.
 
-```php
-app()->get('/protected', ['auth.required', function () {
-  $user = auth()->user();
+## Protected Guest Routes
 
-  // no need to check if user is logged in
+Just like the `auth.required` middleware, Leaf Auth provides a `auth.guest` middleware to protect routes that should only be accessible to guest users. This is useful for routes like the login and register routes.
+
+```php
+app()->get('/login', ['middleware' => 'auth.guest', function () {
+  // this route is only accessible to guest users
 }]);
 ```
 
-## Protected Guest Routes
+If a logged in user tries to access a route protected by the `auth.guest` middleware, they will be redirected to the `/dashboard` route by default.
 
-You can also protect routes that should only be accessible to guest users. This is useful for routes like the login and register routes. You can use the `auth.guest` middleware to protect these routes.
+## Customizing auth middleware
+
+Your application may need you to return different responses for the `auth.required` and `auth.guest` middleware. You can customize the middleware by defining your own function that should be called when the middleware fails.
 
 ```php
+auth()->middleware('auth.required', function () {
+  response()->exit('You need to be logged in to access this route');
+});
+
 auth()->middleware('auth.guest', function () {
-  response()->redirect('/dashboard');
+  response()->exit('You are already logged in');
 });
 ```
 
-You can then use this middleware on your guest routes like this:
+After defining the custom middleware, you can use it in your routes.
 
 ```php
+app()->get('/protected', ['middleware' => 'auth.required', function () {
+  // this route is protected
+}]);
+
 app()->get('/login', ['middleware' => 'auth.guest', function () {
   // this route is only accessible to guest users
 }]);
 ```
 
-This middleware will run before the route is executed. If a user is logged in, the callback function you defined will be executed. This means you can remove the check for a guest user from your route handler.
+You only need to define the custom middleware if the default behavior of the `auth.required` and `auth.guest` middleware does not meet your requirements.
 
 ## Session Guards <Badge type="danger" text="DEPRECATED" />
 

From b6fa2e2cad0ea5ac10d7d45c53073eae30b1d587 Mon Sep 17 00:00:00 2001
From: mychidarko <mickdd22@gmail.com>
Date: Sun, 15 Dec 2024 17:44:36 +0000
Subject: [PATCH 4/8] feat: add createUserFor docs

---
 src/docs/auth/signup.md | 21 +++++++++++++++++++++
 1 file changed, 21 insertions(+)

diff --git a/src/docs/auth/signup.md b/src/docs/auth/signup.md
index a3f25535..96b31f0b 100644
--- a/src/docs/auth/signup.md
+++ b/src/docs/auth/signup.md
@@ -137,6 +137,27 @@ $user = auth()->user();
 
 `fromOAuth()` automatically turns off password encoding, so you don't need to worry doing it manually. If you want to turn off password encoding for normal signups, you can find the documentation [here](#password-hashing).
 
+## Signing up another user <Badge type="tip" text="New" />
+
+When building applications that may require you to sign up users on their behalf, for example, an admin signing up a user, you can use the `createUserFor()` method. This method allows you to create a user without needing to log in as the user. It takes in the user's data and returns the auth user instance if the user is saved successfully.
+
+```php
+$user = auth()->createUserFor([
+  'username' => 'example',
+  'email' => 'example@example.com',
+  'password' => 'password'
+]);
+
+if ($user) {
+  // user is saved
+} else {
+  // user is not saved
+  $error = auth()->errors();
+}
+```
+
+It behaves the same way as the `register()` method, except that it doesn't create a session when the user is saved. The user instance returned can be used to perform operations on the user like assigning roles and more.
+
 ## Unique fields
 
 There are some fields in your database that should not be repeated for different users. For example, you wouldn't want two users to have the same email address. You can configure Leaf Auth to check for unique fields when a user is being registered:

From 83ba60db39597ad916d56fe2b0f9790d18059557 Mon Sep 17 00:00:00 2001
From: mychidarko <mickdd22@gmail.com>
Date: Sun, 15 Dec 2024 17:44:54 +0000
Subject: [PATCH 5/8] feat: add auth find docs

---
 src/docs/auth/login.md | 18 +++++++++++++++++-
 1 file changed, 17 insertions(+), 1 deletion(-)

diff --git a/src/docs/auth/login.md b/src/docs/auth/login.md
index 485f1b25..c2570d10 100644
--- a/src/docs/auth/login.md
+++ b/src/docs/auth/login.md
@@ -163,12 +163,28 @@ Everything after this point is the same as signing up a user normally.
 ::: info OAuth Token
 The `fromOAuth()` method expects an OAuth token to be passed in. This token is usually gotten from the OAuth provider you are using. You can later use this token to make requests to the OAuth provider on behalf of the user. Leaf Auth saves this token so you can retrieve it later using the `auth()->oauthToken()` method.
 
-```php
+```php:no-line-numbers
 $token = auth()->oauthToken();
 ```
 
 :::
 
+## Finding a user by id <Badge type="tip" text="New" />
+
+There are times when you might want to find a user by their id to perform some operations on them while they are NOT logged in. For instance, finding a user by their id to assign a role to them. Leaf Auth provides the `find()` method to do this:
+
+```php
+$user = auth()->find(1);
+
+...
+
+$user->assign('admin');
+
+...
+
+$user->transactions()->create([...]);
+```
+
 ## Auth with no password
 
 Leaf Auth usually expects a password field to authenticate users. This is necessary because most applications require a password to authenticate users. The field is usually named `password`, however, you can configure Leaf Auth to expect a different field:

From 5e54eea52c8992f21e6afb541d776cab7a8ef337 Mon Sep 17 00:00:00 2001
From: mychidarko <mickdd22@gmail.com>
Date: Sun, 15 Dec 2024 17:45:14 +0000
Subject: [PATCH 6/8] feat: add permissions released banner

---
 .vitepress/theme/components/shared/Banner.vue | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.vitepress/theme/components/shared/Banner.vue b/.vitepress/theme/components/shared/Banner.vue
index 7a8ea22e..c51e3e88 100644
--- a/.vitepress/theme/components/shared/Banner.vue
+++ b/.vitepress/theme/components/shared/Banner.vue
@@ -31,7 +31,7 @@ const dismiss = () => {
 <template>
   <div ref="el" class="banner">
     <div class="text">
-      🎉 Leaf MVC v3.8 released. Check out the <a href="https://blog.leafphp.dev/posts/leaf-mvc-3-8" target="_blank">release post</a>
+      🎉 You can now use <a href="/docs/auth/permissions">Roles and permissions</a> natively in your apps.
     </div>
 
     <button type="button" @click="dismiss">

From e7128a2bdb305f5b62a634bc369996d7a6708362 Mon Sep 17 00:00:00 2001
From: mychidarko <mickdd22@gmail.com>
Date: Sun, 15 Dec 2024 18:03:58 +0000
Subject: [PATCH 7/8] feat: add permissions docs

---
 .vitepress/config/sidebar.ts |   2 +-
 src/docs/auth/permissions.md | 286 +++++++++++++++++++++++++++++++++++
 2 files changed, 287 insertions(+), 1 deletion(-)
 create mode 100644 src/docs/auth/permissions.md

diff --git a/.vitepress/config/sidebar.ts b/.vitepress/config/sidebar.ts
index d3712ee5..ba075d23 100644
--- a/.vitepress/config/sidebar.ts
+++ b/.vitepress/config/sidebar.ts
@@ -91,7 +91,7 @@ const sidebar = [
         text: 'Protecting your routes',
         link: '/docs/auth/protected-routes',
       },
-      // { text: 'Updating logged-in user', link: '/docs/auth/update' },
+      { text: 'Roles/Permissions', link: '/docs/auth/permissions' },
       // { text: 'Build your own auth library', link: '/docs/auth/helpers' },
     ],
   },
diff --git a/src/docs/auth/permissions.md b/src/docs/auth/permissions.md
new file mode 100644
index 00000000..b5179cb1
--- /dev/null
+++ b/src/docs/auth/permissions.md
@@ -0,0 +1,286 @@
+# Roles and Permissions <Badge type="warning" text="BETA" />
+
+<!-- markdownlint-disable no-inline-html -->
+
+<script setup>
+import VideoModal from '@theme/components/shared/VideoModal.vue'
+</script>
+
+Authorization and authentication usually come together, but are different. Authentication is the process of verifying who you are usually in the form of signing in or logging in, while authorization is the process of verifying what you can do in the application. Leaf Auth now comes with a built-in way to manage what users can do in your application using roles and permissions.
+
+<!-- ::: details Roles vs Permissions
+
+- Token based authentication is a system where a user is given a token upon login which is then used to authenticate the user on every request. It is the most common authentication system for APIs. This video by Hamy Labs explains how token authentication works
+
+  <VideoModal
+    subject="How Token Authentication Works"
+    description="Many websites use token authentication to secure access to their services. This video explains what tokens are and how token authentication works."
+    videoUrl="https://www.youtube.com/embed/giKeegmeaKw"
+  />
+
+  <br />
+  <br />
+
+- Session-based authentication is a method where, after a user logs in, the server creates a session to remember them. Every time the user makes a request, their session ID is sent back to the server to verify their identity, allowing them to stay logged in while using the app.
+
+  <VideoModal
+    subject="Session Based Authentication | Authentication Series"
+    description="Session-based authentication is a stateful authentication technique where we use sessions to keep track of the authenticated user. In this video, we learn what session-based authentication is, what session is and how session-based authentication is implemented."
+    videoUrl="https://www.youtube.com/embed/gKkBEOq_shs"
+  />
+
+::: -->
+
+## Setting up
+
+To get started, you need to install the Leaf Auth package. You can do this by running the following command:
+
+::: code-group
+
+```bash:no-line-numbers [Leaf CLI]
+leaf install auth
+```
+
+```bash:no-line-numbers [Composer]
+composer require leafs/auth
+```
+
+:::
+
+Once that's done, you can get started creating your roles and permissions, but first, let's understand how roles and permissions relate to your users.
+
+Leaf's authorization system works strictly based on a user role system meaning that users can only have roles, while all the permissions you want to grant to users are attached to roles. Users cannot be assigned permissions directly, and those permissions cannot be revoked from users directly. To assign any permission to a user, you must attach that permission to a role and then assign that role to the user.
+
+## Creating Roles
+
+To create roles and assign permissions to them, you can use the `createRoles()` method on the `Auth` class. This method takes an array of roles and their permissions as an argument. Here's an example:
+
+```php
+auth()->createRoles([
+  'admin' => ['view user', 'view users', 'create user', ...],
+  'user' => ['view user', 'view users'],
+  'guest' => ['view user']
+]);
+```
+
+In the example above, we created three roles: `admin`, `user`, and `guest`. The `admin` role has all the permissions, while the `user` role has fewer permissions. The `guest` role has only one permission.
+
+After creating roles, the next step is to assign roles to users when they are created.
+
+::: details Database Considerations
+Unlike traditional RBAC, Leaf Auth does not store the list of roles and permissions in the database, it only stores a quick reference directly on the user. This design decision was made after weighing the pros and cons of both approaches.
+
+This approach was selected because it has less overhead and doesn't require a lot of database queries to check if a user has a role or permission which makes it more performant, also since we do not allow users to have permissions directly, it makes sense to store the roles directly on the user.
+
+The only major downside to this approach is that querying all users with a specific role or permission is slightly less performant than if we stored the roles and permissions in the database. However, this is a trade-off we are willing to make for the upfront performance benefits.
+:::
+
+## Assigning Roles to Users
+
+To assign roles to users, you can use the `assign()` method on the user, but this means you have to create the user first. Here's an example:
+
+::: code-group
+
+```php{8} [Create an account for another user]
+$user = auth()->createUserFor([
+  'name' => 'John Doe',
+  'email' => 'john@example.com',
+  'password' => 'password'
+]);
+
+if ($user) {
+  $user->assign('admin');  // [!code focus]
+
+  ...
+}
+```
+
+```php{4} [Assign a role to an existing user]
+$user = auth()->find(1);
+
+if ($user) {
+  $user->assign('admin');  // [!code focus]
+
+  ...
+}
+```
+
+:::
+
+You can also assign roles to the currently authenticated user who signed in using the `login()` or `register()` method:
+
+```php
+$success = auth()->login([...]);
+
+if ($success) {
+  auth()->user()->assign('admin');
+}
+
+// or from the register method
+
+$success = auth()->register([...]);
+
+if ($success) {
+  auth()->user()->assign('admin');
+}
+```
+
+Once a user has been assigned a role, they can now perform actions that are allowed by that role. For instance, if a user has the `admin` role, they can perform all the actions that the `admin` role has permissions for.
+
+## Checking a User's Role
+
+To check if a user has a role, you can use the `is()` method on the user. Here's an example:
+
+```php
+if (auth()->user()->is('admin')) {
+  // User is an admin
+}
+```
+
+The `is()` method takes in either a string or an array of roles to check if the user has any of the roles in the array. So if an array is passed, the method will return `true` if the user has any of the roles in the array.
+
+```php
+if (auth()->user()->is(['admin', 'user'])) {
+  // User is an admin or a user
+}
+```
+
+Leaf Auth also comes with a little syntactic sugar to make this easier to check if a user doesn't have a role. You can use the `isNot()` method to check if a user doesn't have a role. Here's an example:
+
+```php
+if (auth()->user()->isNot('admin')) {
+  // User is not an admin
+}
+
+if (auth()->user()->isNot(['admin', 'user'])) {
+  // User is not an admin or a user
+}
+```
+
+## Checking Permissions
+
+Once you assign a role to a user, the user can perform all the actions that the role has permissions for. To check if a user has a permission, you can use the `can()` method on the user. Here's an example:
+
+```php
+if (auth()->user()->can('view user')) {
+  // User can view a user
+}
+```
+
+The `can()` method takes in either a string or an array of permissions to check if the user has any of the permissions in the array. So if an array is passed, the method will return `true` if the user has any of the permissions in the array.
+
+```php
+if (auth()->user()->can(['view user', 'create user'])) {
+  // User can view a user or create a user
+}
+```
+
+Just like the `is()` method, Leaf Auth also comes with a little syntactic sugar to make this easier to check if a user doesn't have a permission. You can use the `cannot()` method to check if a user doesn't have a permission. Here's an example:
+
+```php
+if (auth()->user()->cannot('view user')) {
+  // User cannot view a user
+}
+
+if (auth()->user()->cannot(['view user', 'create user'])) {
+  // User cannot view a user or create a user
+}
+```
+
+## Middleware
+
+In addition to the `is()` and `can()` methods, Leaf Auth also comes with middleware to protect routes based on roles and permissions. There are 4 middleware that come with Leaf Auth that are exactly the same as the functions above:
+
+- `is` - Only allows access if the user has the specified role(s)
+- `isNot` - Only allows access if the user does not have the specified role(s)
+- `can` - Only allows access if the user has the specified permission(s)
+- `cannot` - Only allows access if the user does not have the specified permission(s)
+
+To use the middleware, you can pass the middleware as an array to the route. Here's an example:
+
+```php
+app()->get('/admin', [
+  'middleware' => 'is:admin|user|organizer',
+  function () {
+    return 'Admin Page';
+  }
+]);
+
+app()->get('/user/{user}', [
+  'middleware' => 'can:view user|create user',
+  function () {
+    return 'User Page';
+  }
+]);
+
+app()->get('/guest', [
+  'middleware' => 'isNot:admin',
+  function () {
+    return 'Guest Page';
+  }
+]);
+
+app()->get('/no-access', [
+  'middleware' => 'cannot:view user|create user',
+  function () {
+    return 'No Access Page';
+  }
+]);
+```
+
+In the example above:
+
+- The `/admin` route can only be accessed by users with the `admin`, `user`, or `organizer` roles.
+- The `/user/{user}` route can only be accessed by users with the `view user` or `create user` permissions.
+- The `/guest` route can only be accessed by users who do not have the `admin` role.
+- The `/no-access` route can only be accessed by users who do not have the `view user` or `create user` permissions.
+
+By default, Leaf Auth will show a 404 page if the user does not have the required role or permission to access the route. You can customize this behavior by manually telling Leaf Auth what to do when a user does not have the required role or permission using the `middleware()` method on the `Auth` class. Here's an example:
+
+To use the your selected middleware, you need to tell Leaf Auth what should happen if the role or permission validation fails. You can do this using the `middleware()` method on the `Auth` class. Here's an example:
+
+```php
+auth()->middleware('is', function () {
+  response()->redirect('/login');
+});
+```
+
+Over here, we're telling Leaf Auth to redirect the user to the login page if the user does not have the required role to access the route. This will only work for the `is` middleware. You can also use the `isNot`, `can`, and `cannot` middleware in the same way.
+
+## Unassigning Roles
+
+To unassign a role from a user, you can use the `unassign()` method on the user. Here's an example:
+
+```php:no-line-numbers
+auth()->user()->unassign('admin');
+```
+
+## Listing Roles and Permissions
+
+To list all the roles and permissions you registered using the `createRoles()` method, you can use the `roles()` method on the `Auth` class. Here's an example:
+
+```php:no-line-numbers
+$roles = auth()->roles();
+```
+
+The `roles()` method will return an array of all the roles and their permissions just like you registered them.
+
+## Getting a User's Roles
+
+To get a user's roles, you can use the `roles()` method on the user:
+
+```php:no-line-numbers
+$roles = auth()->user()->roles();
+```
+
+The `roles()` method will return an array of all the roles the user has without the permissions. It will also return an empty array if the user has no roles.
+
+## Getting a User's Permissions
+
+To get a user's permissions, you can use the `permissions()` method on the user:
+
+```php:no-line-numbers
+$permissions = auth()->user()->permissions();
+```
+
+The `permissions()` method will return an array of all the permissions the user has without the roles. It will also return an empty array if the user has no permissions.

From 85cb97764504670468d96547a77c1168f5e5d3cb Mon Sep 17 00:00:00 2001
From: mychidarko <mickdd22@gmail.com>
Date: Sun, 15 Dec 2024 18:11:13 +0000
Subject: [PATCH 8/8] fix: patch up info

---
 src/docs/index.md     | 20 ++++++++++++++++++--
 src/docs/mvc/index.md |  2 +-
 2 files changed, 19 insertions(+), 3 deletions(-)

diff --git a/src/docs/index.md b/src/docs/index.md
index 9aeb55dd..bdb12d06 100644
--- a/src/docs/index.md
+++ b/src/docs/index.md
@@ -63,9 +63,23 @@ Don't worry if you're not familiar with these concepts, we'll provide videos and
 
 Leaf is built with many classes and components, but for simpler apps or APIs, it also offers a functional mode. This lets you use Leaf and its modules without class imports, instantiation, or lengthy namespaces—keeping things simple and streamlined.
 
-Of course, you can still use Leaf in class mode if you prefer that. Here's an example of a simple Leaf app in functional mode:
+Of course, you can still use Leaf in class mode if you prefer that. Here's an example of a simple Leaf app in both modes:
 
-```php
+::: code-group
+
+```php [Functional Mode]
+<?php
+
+require __DIR__ . '/vendor/autoload.php';
+
+app()->get('/', function () {
+  response()->json(['message' => 'Leaf is amazing!']);
+});
+
+app()->run();
+```
+
+```php [Class Mode]
 <?php
 
 use Leaf\App;
@@ -81,6 +95,8 @@ $app->get('/', function () use ($app) {
 $app->run();
 ```
 
+:::
+
 The documentation will usually show you how to use modules in functional mode as this is the default mode for Leaf. However, if you are migrating from another framework or you prefer to use Leaf in class mode, you can always instantiate the classes and use them as you would in any other framework.
 
 ## Getting Started
diff --git a/src/docs/mvc/index.md b/src/docs/mvc/index.md
index 32b3c1c2..522f9381 100644
--- a/src/docs/mvc/index.md
+++ b/src/docs/mvc/index.md
@@ -13,7 +13,7 @@ Leaf is a lightweight PHP framework with a ton of loosely coupled libraries that
 MVC stands for Model-View-Controller. It is a pattern that separates your application into three distinct parts:
 
 - Models: These are the classes that represent your data. They are responsible for interacting with your database, and for validating your data.
-- Views: These are the files that are responsible for displaying your data to your user. They are usually written in HTML, but can also be written in other templating languages like [BareUI](/docs/frontend/bareui/) or [Blade](/docs/frontend/blade/) or frameworks like [Vue](https://vuejs.org/) or [React](https://reactjs.org/)
+- Views: These are the files that are responsible for displaying your data to your user. They are usually written in HTML, but can also be written in other templating languages like [BareUI](/docs/frontend/bareui) or [Blade](/docs/frontend/blade) or frameworks like [Vue](https://vuejs.org/) or [React](https://reactjs.org/)
 - Controllers: These are the classes that are responsible for handling the user's request, and for returning the appropriate response.
 
 ::: details New to MVC?