feat: update auth & db docs

Author: mychidarko

.vitepress/config/sidebar.ts

@@ -46,16 +46,6 @@ const sidebar = [
       { text: 'CORS', link: '/docs/http/cors' },
     ],
   },
-  {
-    text: 'Sessions',
-    // collapsible: true,
-    // collapsed: true,
-    items: [
-      { text: 'Using Sessions', link: '/docs/http/session' },
-      { text: 'Session Flash', link: '/docs/http/flash' },
-      { text: 'Cookies', link: '/docs/http/cookies' },
-    ],
-  },
   {
     text: 'Config & Deployment',
     // collapsible: true,
@@ -106,6 +96,16 @@ const sidebar = [
       { text: 'Build your own auth library', link: '/docs/auth/helpers' },
     ],
   },
+  {
+    text: 'Sessions',
+    // collapsible: true,
+    // collapsed: true,
+    items: [
+      { text: 'Using Sessions', link: '/docs/http/session' },
+      { text: 'Session Flash', link: '/docs/http/flash' },
+      { text: 'Cookies', link: '/docs/http/cookies' },
+    ],
+  },
   {
     text: 'Security',
     // collapsible: true,

.vitepress/theme/styles/index.css

@@ -36,7 +36,7 @@
 }
 
 html.dark {
-  --vp-c-banner: var(--vp-c-bg-soft);
+  --vp-c-banner: #0e5f3c;
   --vp-code-color: #3eaf7c;
   --vp-c-bg: #001e26;
   --vp-c-bg-alt: #001318;

src/docs/auth/index.md

@@ -84,7 +84,7 @@ That's all you need to do. Leaf Auth will automatically connect to your database
 
 Leaf Auth doesn't give you any structure for your database, with that, you can structure your database in any way you prefer. However, there are some things you should note:
 
-1. By default, Leaf Auth assumes that your database primary key is `id`. If you have a database where you are using another field, say `admin_id` as the primary key, you will need to tell Leaf the name of your primary key. You can do this using the `ID_KEY` config:
+1. By default, Leaf Auth assumes that your database primary key is `id`. If you have a database where you are using another field, say `admin_id` as the primary key, you will need to tell Leaf the name of your primary key. You can do this using the `id.key` config:
 
     ```php:no-line-numbers
     auth()->config('id.key', 'admin_id');

src/docs/auth/login.md

@@ -50,7 +50,7 @@ $data = auth()->login([
   'password' => 'password'
 ]);
 
-if($data) {
+if ($data) {
   // User is authenticated
   $token = $data->token;
   $user = $data->user;
@@ -70,13 +70,33 @@ Leaf uses token based authentication by default which uses a JWT to authenticate
 auth()->config('session', true);
 ```
 
-With this, a new login will create a session for the user. If your app requires users to be redirected to a different page after login, you can configure Leaf Auth to do just that:
+With the addition of session auth, `login()` will automatically start a session, but will leave redirects and every other thing to you:
 
-```php:no-line-numbers
-auth()->config('session.loginRedirect', '/dashboard');
+```php
+auth()->config('session', true);
+
+...
+
+// session is automatically started
+$data = auth()->login([
+  'email' => '[email protected]',
+  'password' => 'password'
+]);
+
+if ($data) {
+  // User is authenticated
+  $user = $data->user;
+
+  response()->redirect('/dashboard');
+} else {
+  // User is not authenticated
+  $error = auth()->errors();
+}
 ```
 
-You can also control things like the cookie settings and more:
+This lets you handle complex control flows...or the simple redirect ones in a manner you prefer.
+
+If you need finer control over how PHP creates your session, you can add your own config to the `session.cookie` config:
 
 ```php
 auth()->config('session.cookie', [
@@ -86,12 +106,6 @@ auth()->config('session.cookie', [
 ]);
 ```
 
-You can also generate JWT tokens for your sessions if you want to:
-
-```php:no-line-numbers
-auth()->config('session.jwt', true);
-```
-
 ## 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:
@@ -220,7 +234,7 @@ $data = auth()->update([
   'email' => '[email protected]'
 ]);
 
-if(!$data) {
+if (!$data) {
   $error = auth()->errors();
   // ['email' => 'The email already exists']
 }
@@ -235,12 +249,17 @@ auth()->logout();
 
 // or redirect the user after logout
 auth()->logout('/login');
+
+// or redirect to a named route
+auth()->logout(['homepage']);
 ```
 
-By default, the logout method will just end the user's session. If you want to perform a custom operation when a user logs out, you can set a handler for the logout operation:
+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/protected-routes.md

@@ -47,8 +47,8 @@ app()->get('/protected', function () {
   } else {
     // user is not logged in
     response()->json([
-      "error" => "Unauthorized",
-      "data" => auth()->errors(),
+      'error' => 'Unauthorized',
+      'data' => auth()->errors(),
     ], 401);
   }
 });

src/docs/auth/signup.md

@@ -80,7 +80,7 @@ $data = auth()->register([
   'password' => 'password'
 ]);
 
-if($data) {
+if ($data) {
   // User is authenticated
   $token = $data->token;
   $user = $data->user;
@@ -107,7 +107,7 @@ $data = auth()->register([
   'password' => 'password'
 ]);
 
-if(!$data) {
+if (!$data) {
   $error = auth()->errors();
   // ['email' => 'The email already exists']
 }
@@ -158,16 +158,26 @@ Leaf uses token based authentication by default which uses a JWT to authenticate
 auth()->config('session', true);
 ```
 
-This however won't automatically log in a user after registration meaning no session will be created after a user signs up. If you want to automatically log in a user after registration, you can configure Leaf Auth to do that:
+Switching to session auth does not change the default behaviour of the `register()` method. It won't create a session or do anything fancy by default. If you want to create a session immediately after signing a user up, you can pass true to the `session.register` config:
 
 ```php:no-line-numbers
 auth()->config('session.register', true);
-```
 
-You can also set the URL where your app should redirect users to after registration:
+...
 
-```php:no-line-numbers
-auth()->config('session.registerRedirect', '/dashboard');
+// will create a session
+$data = auth()->register([
+  'username' => 'example',
+  'email' => '[email protected]',
+  'password' => 'password'
+]);
+
+if ($data) {
+  response()->redirect('/dashboard');
+} else {
+  $error = auth()->errors();
+  // ['email' => 'The email already exists']
+}
 ```
 
 You can also control things like the cookie settings and more:
@@ -179,9 +189,3 @@ auth()->config('session.cookie', [
   'samesite' => 'lax'
 ]);
 ```
-
-You can also generate JWT tokens for your sessions if you want to:
-
-```php:no-line-numbers
-auth()->config('session.jwt', true);
-```

src/docs/database/builder.md

@@ -224,6 +224,41 @@ db()
 
 This will delete the row in the users table with the `id` of 1.
 
+## Database Transactions
+
+Database transactions are a way to ...
+Leaf DB allows you to create database transactions using the `transaction()` method. It takes in a callable which is every query you want to perform as part of your transaction.
+
+```php
+db()->transaction(function ($db) {
+  $db->insert('purchases')->params(...)->execute();
+  $db->update('balances')->params(...)->where(...)->execute();
+
+  // you can even do external stuff here
+  $res = fetch()->post(...)
+
+  $doSomething = $res->data;
+
+  ...
+});
+```
+
+If anything in the function fails, Leaf will automatically rollback every change that has been made in the database till that point and return `false`. You can get the associated error using the `errors()` method.
+
+```php
+$success = db()->transaction(function () {
+  ...
+});
+
+if ($success) {
+  // do something
+} else {
+  $errors = db()->errors();
+}
+```
+
+This is useful especially when you have a set of queries that rely on third party influence.
+
 ## Hiding columns from results
 
 Sometimes you might want to hide certain columns from the results of a query. For instance, you might want to hide the password column from the results of a query on the users table. Leaf DB provides a `hide()` method that allows you to do this.

src/docs/http/caching.md

@@ -32,10 +32,10 @@ An ETag is a unique identifier for a resource URI. After setting the Etag header
 Setting an ETag with Leaf is very simple. Invoke Leaf’s etag method in your route callback, passing it a unique ID as the first and only argument.
 
 ```php
-use \Leaf\Http\Headers;
+use Leaf\Http\Cache;
 
 app()->get('/', function () {
-  Headers::etag('unique-tag');
+  Cache::etag('unique-tag');
 
   echo 'This will be cached after the initial request!';
 });
@@ -50,11 +50,11 @@ Used in conjunction with the Leaf application’s etag or lastModified methods,
 The expires method accepts one argument: an integer UNIX timestamp, or a string to be parsed with `strtotime()`.
 
 ```php
-use \Leaf\Http\Headers;
+use Leaf\Http\Cache;
 
 app()->get('/', function () {
-  Headers::etag('unique-tag');
-  Headers::expires('+1 week');
+  Cache::etag('unique-tag');
+  Cache::expires('+1 week');
 
   echo 'This will be cached client-side for one week';
 });
@@ -67,10 +67,10 @@ A Leaf provides built-in support for HTTP caching using the resource’s last mo
 Setting a last modified date with Leaf is very simple. You only need to invoke the Leaf’s lastModified() method in your route callback passing in a UNIX timestamp of the last modification date for the given resource. Be sure the lastModified() method’s timestamp updates along with the resource’s last modification date; otherwise, the browser client will continue serving its outdated cache.
 
 ```php
-use \Leaf\Http\Headers;
+use Leaf\Http\Cache;
 
 app()->get('/', function () {
-  Headers::lastModified(1617383991);
+  Cache::lastModified(1617383991);
 
   echo 'This will be cached after the initial request!';
 });
@@ -81,7 +81,7 @@ app()->get('/', function () {
 There are other cache-related headers that Leaf doesn't provide direct methods for. You can set these headers directly using Leaf's Headers::set() method.
 
 ```php
-use \Leaf\Http\Headers;
+use Leaf\Http\Headers;
 
 app()->get('/', function () {
   Headers::set('Cache-Control', 'public, max-age=3600');

src/docs/utils/fetch.md

@@ -77,38 +77,48 @@ It gets even simpler when you're making a GET or POST request. Fetch provides so
 GET requests are the most common type of request you'll make when fetching data from an API. Fetch makes it easy to make GET requests using the global `fetch()` function. Here's an example of how you can make a GET request using Fetch:
 
 ```php
-$res = fetch("https://jsonplaceholder.typicode.com/todos/");
+$res = fetch()->get('https://jsonplaceholder.typicode.com/todos/');
 
 // data returned is saved in the $data property just like axios
 response()->json($res->data);
 ```
 
-Every request made using Fetch returns a `FetchResponse` object. This object contains the response data, status code, headers, and more. You can access the response data using the `data` property.
+Or you pass the url directly to the `fetch()` function.
 
-## Making POST Requests
+```php
+$res = fetch('https://jsonplaceholder.typicode.com/todos/');
+
+// data returned is saved in the $data property just like axios
+response()->json($res->data);
+```
 
-POST requests are used to send data to a server to create or update a resource. You can make POST requests using Fetch by passing an array of data as the second argument to the `fetch()` function. Here's an example:
+## Making Other Requests
+
+Fetch works just like the Leaf router, in a sense that every request type has a shortcut method. You can call `get()`, `post()`, `put()`, `patch()`, `delete()` and `options()` to make any kind of request you want.
 
 ```php
-$res = fetch("https://jsonplaceholder.typicode.com/posts", [
-  "title" => "foo",
-  "body" => "bar",
-  "userId" => 1
+$res = fetch()->post('https://jsonplaceholder.typicode.com/posts', [
+  'title' => 'foo',
+  'body' => 'bar',
+  'userId' => 1
 ]);
 
+fetch()->put(...);
+fetch()->patch(...);
+fetch()->delete(...);
+fetch()->options(...);
+
 response()->json($res->data);
 ```
 
-Once `fetch()` detects that you're passing an array as the second argument, it automatically converts the request to a POST request.
-
 ## Setting Base URLs
 
 Base URLs are useful when you're making requests to the same server or API. One popular use case for base URLs is when you're working with a REST API as it allows you to ignore typing lengthy URLs for every request.
 
-You can set a base URL for all your requests using the `baseUrl()` method on the `Fetch` class.
+You can set a base URL for all your requests using the `baseUrl()` method on the `fetch` function.
 
 ```php
-Leaf\Fetch::baseUrl('https://jsonplaceholder.typicode.com');
+fetch()->baseUrl('https://jsonplaceholder.typicode.com');
 ```
 
 Now you can make requests without specifying the full URL.
@@ -118,7 +128,7 @@ Now you can make requests without specifying the full URL.
 $response = fetch('/todos');
 
 // https://jsonplaceholder.typicode.com/posts
-$response = fetch('/posts', [
+$response = fetch()->post('/posts', [
   'title' => 'foo',
   'body' => 'bar',
   'userId' => 1,

src/public/sponsors.json

@@ -393,6 +393,11 @@
       "url": "https://github.com/1mahdimf",
       "img": "https://avatars.githubusercontent.com/u/8771082?v=4"
     },
+    {
+      "name": "Isaac",
+      "url": "https://github.com/isaac-araujo",
+      "img": "https://avatars.githubusercontent.com/u/84479744?v=4"
+    },
     {
       "name": "pakuningratan",
       "url": "https://github.com/pakuningratan",