feat: update auth docs

Author: mychidarko

.vitepress/config/sidebar.ts

@@ -86,7 +86,7 @@ const sidebar = [
       // { text: 'Auth Config', link: '/docs/auth/config' },
       { text: 'User Login', link: '/docs/auth/login' },
       { text: 'User Sign Up', link: '/docs/auth/signup' },
-      // { text: 'Auth Session', link: '/docs/auth/session' },
+      { text: 'Auth User', link: '/docs/auth/user' },
       {
         text: 'Protecting your routes',
         link: '/docs/auth/protected-routes',

src/docs/auth/login.md

@@ -65,47 +65,7 @@ $data = auth()->data();
 // ['user' => [...], 'accessToken' => '...', 'refreshToken' => '...']
 ```
 
-If you want to use a couple of fields from the user within your application, you can use the user method:
-
-## The user object
-
-The `user()` method gives you access to an object configured to the user's data. This object is a simple way to access the user's data without having to go through the data array. There are many things you can do with the user object:
-
-- Getting user information (including hidden fields)
-- Token/Session management
-- Fetching related data from your database
-
-```php
-// return all user data without hidden fields
-$user = auth()->user()->get();
-
-// pick specific fields
-$username = auth()->user()->username;
-$email = auth()->user()->email;
-
-// get the user's data + tokens
-$data = auth()->user()->getAuthInfo();
-```
-
-If your user has one to many relationships with other models, you can fetch related data using the user object:
-
-```php
-$posts = auth()->user()->posts();
-// will return a Leaf DB instance with posts by the current user
-// SELECT * FROM posts WHERE user_id = $current_user_id
-```
-
-You can further filter the data by using any of the Leaf DB methods:
-
-```php:no-line-numbers
-$posts = auth()->user()->posts()->where('title', 'like', '%leaf%')->get();
-```
-
-Note that the method name should be the same as the table name in your database.
-
-```php:no-line-numbers
-$posts = auth()->user()->transactions()->where('amount', '>', 1000)->get();
-```
+If you want to use a couple of fields from the user within your application, you can use the user method. You can find the documentation for the Auth user method [here](/docs/auth/user).
 
 ## Switching to session auth
 
@@ -236,59 +196,3 @@ auth()->config('session.lifetime', 0); // never expire
 ```
 
 :::
-
-## Updating a logged-in user
-
-Updating user information means allowing users to change their details (like username, email, or password) in your application. It is a very common feature in most applications.
-
-Leaf provides an `update()` method that allows you to update a user's information.
-
-```php
-$user = auth()->update($data);
-```
-
-### Unique values
-
-Leaf Auth allows you to set unique fields which 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 updated:
-
-```php:no-line-numbers
-auth()->config('unique', ['email', 'username']);
-```
-
-Now if a user tries to update their profile with an email or username that already exists in the database, Leaf Auth will return an error. You can get the error message using the `errors()` method.
-
-```php
-$success = auth()->update([
-  'username' => 'example',
-  'email' => '[email protected]'
-]);
-
-if (!$success) {
-  $error = auth()->errors();
-  // ['email' => 'email already exists']
-}
-```
-
-## Signing a user out
-
-When a user chooses to end their session, or their session expires, you can sign them out using the `logout()` method. This method will end the user's session or delete their token.
-
-```php
-auth()->logout();
-
-// or redirect the user after logout
-auth()->logout('/login');
-
-// or redirect to a named route
-auth()->logout(['homepage']);
-```
-
-If you want to perform a custom operation when a user logs out, you can set a handler for the logout operation:
-
-```php
-auth()->config('session.logout', function () {
-  // your logout handler
-});
-```
-
-This will ignore whatever route is passed into the `logout()` method and rely solely on the function passed into the session.logout config.

src/docs/auth/update.md

@@ -0,0 +1,144 @@
+# User Operations
+
+After successfully logging in or registering a user, Leaf Auth provides a bunch of functionality that you can use to manage your users. These range from updating user details to other CRUD operations.
+
+## Getting user information
+
+You can usually get the current user's information using the `data()` method, however, the output is an array of the user's data together with the tokens which is not very convenient for use within your application.
+
+```php
+$data = auth()->data();
+// ['user' => [...], 'accessToken' => '...', 'refreshToken' => '...']
+```
+
+The `user()` method allows you to pick out exactly the information you need from the user's data. If you need all the user's data, you can use the `get()` method:
+
+```php
+$user = auth()->user()->get();
+
+// or pick specific fields
+$email = auth()->user()->email;
+$username = auth()->user()->username;
+```
+
+Picking specific fields also gives you access to fields you may have hidden using the auth config. This is useful because it allows you to perform operations on the user's data without mistakenly exposing hidden fields.
+
+```php
+auth()->config('hidden', ['secret_field']);
+
+$secretField = auth()->user()->secret_field;
+```
+
+While this may seem like a lot of work, it's a good way to ensure that your user's data is secure and only accessible where needed.
+
+## User relationships
+
+Relationships are a way to connect different models in your application. For instance, a user may have many posts, or a user may have many transactions. Using relationships, you can fetch related data from your database. If you have a user model with a one-to-many relationship with a posts model, you can fetch the user's posts using the user object:
+
+```php
+$posts = auth()->user()->posts();
+// will return a Leaf DB instance with posts by the current user
+// SELECT * FROM posts WHERE user_id = $current_user_id
+```
+
+You can further filter the data by using any of the Leaf DB methods:
+
+```php:no-line-numbers
+$posts = auth()->user()->posts()->where('title', 'like', '%leaf%')->get();
+```
+
+You can do this by calling whatever table your user is related to as a method on the user object. For instance, if you want to grab all user transactions from the `transactions` table, you can call the `transactions()` method on the user object. If you want to grab all books your user has read from the `read_books` table, you can call the `readBooks()` method on the user object.
+
+It will return a Leaf DB instance with the related data. You can further filter the data by using any of the Leaf DB methods:
+
+```php:no-line-numbers
+$posts = auth()
+  ->user()
+  ->transactions()
+  ->where('amount', '>', 1000)
+  ->get();
+
+$books = auth()
+  ->user()
+  ->readBooks()
+  ->where('title', 'Building with Leaf')
+  ->first();
+```
+
+## Updating a logged-in user
+
+Updating user information means allowing users to change their details (like username, email, or password) in your application. It is a very common feature in most applications.
+
+Leaf provides an `update()` method that allows you to update a user's information. It returns `true` if the user is successfully updated and `false` if the user is not updated. You can get the error message using the `errors()` method.
+
+```php
+$success = auth()->update($data);
+
+if ($success) {
+  // User is updated
+} else {
+  // User is not updated
+  $error = auth()->errors();
+}
+```
+
+### Unique values
+
+Leaf Auth allows you to set unique fields which 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 updated:
+
+```php:no-line-numbers
+auth()->config('unique', ['email', 'username']);
+```
+
+Now if a user tries to update their profile with an email or username that already exists in the database, Leaf Auth will return an error. You can get the error message using the `errors()` method.
+
+```php
+$success = auth()->update([
+  'username' => 'example',
+  'email' => '[email protected]'
+]);
+
+if (!$success) {
+  $error = auth()->errors();
+  // ['email' => 'email already exists']
+}
+```
+
+## Password reset
+
+Leaf Auth doesn't have a full built-in password reset flow which involves sending an email to the user with a link to reset their password. This may be added in the future, but for now, Leaf Auth comes with a simple `updatePassword()` method that allows you to change a user's password. It takes care of verifying the old password and hashing the new password.
+
+```php
+$success = auth()->updatePassword($oldPassword, $newPassword);
+
+if ($success) {
+  // Password is updated
+} else {
+  // Password is not updated
+  $error = auth()->errors();
+}
+```
+
+## Signing a user out
+
+When a user chooses to end their session, or their session expires, you can sign them out using the `logout()` method. This method will end the user's session or delete their token.
+
+```php
+auth()->logout();
+
+// or redirect the user after logout
+auth()->logout('/login');
+
+// or redirect to a named route
+auth()->logout(['homepage']);
+```
+
+If you want to perform a custom operation when a user logs out, you can set a handler for the logout operation:
+
+```php
+auth()->config('session.logout', function () {
+  // your logout handler
+});
+```
+
+This will ignore whatever route is passed into the `logout()` method and rely solely on the function passed into the session.logout config.