diff --git a/.vitepress/config/sidebar.ts b/.vitepress/config/sidebar.ts
index ba075d23..8b21e630 100644
--- a/.vitepress/config/sidebar.ts
+++ b/.vitepress/config/sidebar.ts
@@ -151,12 +151,13 @@ const sidebar = [
// collapsed: true,
items: [
{ text: 'Leaf + MVC', link: '/docs/mvc/' },
+ { text: 'Leaf MVC v4', link: '/docs/mvc/mvc4' },
{ text: 'Controllers', link: '/docs/mvc/controllers' },
// { text: 'Views', link: '/docs/frontend/mvc' },
{ text: 'Models', link: '/docs/database/models' },
{ text: 'Migrations', link: '/docs/database/migrations' },
{ text: 'JSON Schema', link: '/docs/database/schema' },
- // { text: 'Schema Files', link: '/docs/database/files' },
+ { text: 'Schema Files', link: '/docs/database/files' },
{ text: 'Seeders', link: '/docs/database/seeders' },
{ text: 'Factories', link: '/docs/database/factories' },
{ text: 'Writing Commands', link: '/docs/mvc/commands' },
diff --git a/.vitepress/future/files.md b/src/docs/database/files.md
similarity index 75%
rename from .vitepress/future/files.md
rename to src/docs/database/files.md
index ea85d448..7e8bf2c2 100644
--- a/.vitepress/future/files.md
+++ b/src/docs/database/files.md
@@ -1,14 +1,12 @@
-# Schema Files
+# Schema Files ALPHA v4+
-Leaf MVC inherited all the teachings of Laravel and Ruby on Rails, including the use of migrations, seeders, and factories which made creating, testing and seeding databases a breeze. It even introduced schema files, allowing you to generate migrations from JSON data. While helpful, this added complexity and clutter to projects. To simplify things, we’re moving away from the Rails/Laravel approach and creating a more streamlined, Leaf-like solution.
+Leaf MVC inherited all the teachings of Laravel and Ruby on Rails, including the use of migrations, seeders, and factories which made creating, testing and seeding databases a breeze. While this is great and has been tried and tested over the years, having multiple files for a single database table can be a bit of a hassle. This is why we introduced Schema Files in Leaf MVC v4.
## What are Schema Files?
Schema files build on the JSON schema idea we introduced in earlier Leaf MVC versions, but they take things further. Instead of juggling separate files for migrations, seeders, and factories, you can handle everything in one place. They’re written in YAML, so they’re easy to read and work with—no extra hassle, no repeating yourself.
```yml [flights.yml]
-increments: true
-timestamps: true
columns:
to: string
from: string
@@ -17,9 +15,9 @@ columns:
seeds:
count: 10
data:
- to: 'faker:city'
- from: 'faker:city'
- identifier: 'faker:uuid'
+ to: '@faker.city'
+ from: '@faker.city'
+ identifier: '@faker.uuid'
```
## Creating a Schema File
@@ -33,36 +31,39 @@ php leaf g:schema
Remember, every schema file is tied to a table in your database. When you run the command above, Leaf will create a schema file in your `app/database` directory with the name `.yml`. Here’s an example:
```bash:no-line-numbers
-php leaf g:schema users
+php leaf g:schema posts
```
-This will create a schema file at `app/database/users.yml` which looks like this:
+This will create a schema file at `app/database/posts.yml` which looks like this:
-```yml [users.yml]
-increments: true
-timestamps: true
+```yml [posts.yml]
+# schema files add auto-increments and timestamps by default
+
+# you can add all the columns you want under the columns key
columns:
name: string
- email:
+ identifier:
type: string
- length: 255
unique: true
- password: string
- email_verified_at: timestamp
+ verified_at:
+ type: timestamp
+ nullable: true
+
+# you can add foreign ids for other models under the relationships key key
+relationships:
+ - User
+# seeds are optional and can be used to populate the database with dummy data
seeds:
- count: 10
+ count: 5
+ truncate: true
data:
- name: 'faker:name'
- email: 'faker:email'
- password: 'hash:password'
+ name: '@faker.name'
+ identifier: '@faker.uuid'
+ verified_at: '@tick.format:YYYY-MM-DD HH:mm:ss'
```
-Breaking down this file, we have:
-
-- `increments`: This is used to set the default id of the table. If set to `true`, the table will have an auto-incrementing id. If set to `false`, the table will not have an id, and you can set your own primary key.
-
-- `timestamps`: This is used to set timestamps on the table. If set to `true`, the table will have `created_at` and `updated_at` columns. If set to `false`, the table will not have timestamps.
+Breaking this file down, there are three main sections:
- `columns`: This is used to set the columns of the table. The key is the column name and the value is a key value pair of column properties. The available properties are:
- `type`: The type of the column. This can be `string`, `integer`, `timestamp` or any type supported by Laravel's Eloquent.
@@ -80,9 +81,31 @@ Breaking down this file, we have:
- `seeds`: This is used to set the seeders of the table. The available properties are:
- `count`: This is used to set the number of seeds to generate.
- - `data`: This is used to set the data of the seeds. The key is the column name and the value is the value of the column. You can use `faker:[value]` to generate fake data for the column.
+ - `data`: This is used to set the data of the seeds. The key is the column name and the value is the value of the column. You can use `@faker.[value]` to generate fake data for the column.
- `truncate`: This is used to truncate the table before seeding.
+- `relationships`: This is used to set the relationships of the table. The value is an array of models the table is related to. This is used to generate foreign keys for the table.
+
+Besides these, Schema files also set a lot of defaults for you. For instance, the `id` column is set as the primary key and auto-incrementing by default. Timestamps are also added by default. You can override these defaults by adding the `id` and `timestamps` keys to your schema file. Here's an example:
+
+```yml:no-line-numbers [posts.yml]
+increments: false # this will remove the auto-incrementing id column
+timestamps: false # this will remove the timestamps columns
+```
+
+Once you turn off auto-increments, you can add your own `id` column. Here's an example:
+
+```yml:no-line-numbers [posts.yml]
+increments: false
+
+columns:
+ id:
+ type: integer
+ primary: true
+
+...
+```
+
## Database tables
Traditionally, migrations are used to create database tables and modify them. In Leaf MVC, every schema file is tied to a particular table which is the name of the file. All you need to do is modify the columns of the table using the `columns` key in your schema file. Here's an example:
@@ -162,17 +185,17 @@ In the end, this means you can continue to use `php leaf db:rollback` to roll ba
Database seeds are a way to populate a database with initial data. This initial data can be used to set up default values or pre-populate a database with test data. Database seeds typically contain small amounts of data, such as default settings, test data, or sample records.
-Seeders are used to populate your database with dummy data. In Leaf MVC, you can create seeders in your database files. The `seeders` key in your database file is used to create seeders. Here's an example of a seeder:
+Seeders are used to populate your database with dummy data. In Leaf MVC, you can create seeders in your database files. The `seeds` key in your database file is used to create seeders. Here's an example of a seeder:
```yml [users.yml]
seeds:
data:
- name: 'Example User'
email: 'example@example.com'
- password: 'hash:password'
+ password: '@hash:passwordForThisUser' # @hash requires leafs/password
- name: 'Another User'
email: 'another@example.com'
- password: 'hash:password'
+ password: '@hash:passwordForThisUser' # @hash requires leafs/password
```
In this example, we create a seeder that seeds the `users` table with two example users. We are passing an array of seeds to the `data` key, each seed being a key value pair of column name and value.
@@ -185,7 +208,7 @@ seeds:
data:
name: 'Example User'
email: 'example@example.com'
- password: 'hash:password'
+ password: '@hash:password'
```
After creating your seeder, you can run your seeders using the `db:seed` command:
@@ -196,15 +219,15 @@ php leaf db:seed
This will generate 10 seeds for the `users` table with the same data which is not very useful. To generate multiple fake seeds, you can use what other frameworks call a factory.
-In Leaf MVC, factories and seeders are the same thing as we believe this confusion is unnecessary. If you want to generate fake data for your seeders, you can add `faker:[value]` as the value of a column in your seeder. Here's an example:
+In Leaf MVC, factories and seeders are the same thing as we believe this confusion is unnecessary. If you want to generate fake data for your seeders, you can add `@faker.[value]` as the value of a column in your seeder. Here's an example:
```yml{4,5} [users.yml]
seeds:
count: 10
data:
- name: 'faker:name'
- email: 'faker:email'
- password: 'hash:password'
+ name: '@faker.name'
+ email: '@faker.email'
+ password: '@hash:password'
```
In this example, we're generating 10 fake seeds for the `users` table.
diff --git a/src/docs/mvc/mvc4.md b/src/docs/mvc/mvc4.md
new file mode 100644
index 00000000..1d3a9ff7
--- /dev/null
+++ b/src/docs/mvc/mvc4.md
@@ -0,0 +1,225 @@
+# Leaf MVC 4 ALPHA
+
+
+
+
+
+Leaf MVC 4 is a new version of the Leaf MVC framework that is currently in development. It is designed to be more flexible and easier to use than v3 and comes with a ton of improvements, enhanced simplicity, new features, and a more modern codebase with cutting-edge features tailored to improve your development experience. While working on Leaf MVC 4, we were able to backport some of the features to Leaf MVC 3, so if you have used Leaf MVC 3.8 or later, switching to v4 should be a breeze.
+
+
+
+
+
+## Key Highlights
+
+Here are some of the key highlights of Leaf MVC 4:
+
+1. Minimalist Philosophy
+
+- Smaller Core: Streamlined codebase for faster performance and reduced footprint.
+- Modular Architecture: Customize your projects with opt-in integrations.
+
+2. Simplified Folder Structure
+
+- Modularized structure with flexibility to include only what you need.
+- Clear separation of concerns: Controllers, Models, Views, and Configs.
+
+3. Enhanced Developer Tools
+
+- YAML-based database schema management.
+- Console commands with interactive prompts.
+- Automatic setup of Leaf modules.
+
+## Installation
+
+To install Leaf MVC 4, you can use Composer:
+
+```bash:no-line-numbers
+composer create-project leafs/mvc:v4.0-alpha my-app
+```
+
+This will create a new Leaf MVC 4 project in the `my-app` directory. Since Leaf MVC 4 is still in alpha, you can't install it using the Leaf CLI tool yet, but we'll keep you updated as soon as it's available.
+
+## Folder Structure
+
+Leaf MVC ships with a really lean folder structure that is designed to be flexible, easy to understand and easy to work with, especially for beginners. Here's a quick overview of the folder structure:
+
+```bash
+├───app
+│ ├── controllers
+│ ├── database
+│ ├── models
+│ ├── routes
+│ └── views
+│ └── errors
+└───public
+ └───assets
+ ├── css
+ └── img
+```
+
+- `app`: Contains all the application code including controllers, models, views, and routes, as well as your database files.
+- `public`: Contains all the publicly accessible files including assets like CSS and images.
+
+This is much leaner than the folder structure in Leaf MVC 3, which had a lot of directories that were not always necessary. Another thing to note in v4 is that the `config` directory has been removed and configuration files are now provided automatically by Leaf. However, you can still create a `config` directory if you need to add custom configuration files or use the `php leaf config:publish` command to publish the default configuration files.
+
+Also, although this is the default folder structure, if Leaf or any of its modules require additional directories, they will be created automatically. For instance, Blade templates will create a `storage/views` directory for compiled views.
+
+## Customizable view layer
+
+Leaf MVC 4 comes with a customizable view layer that not only allows you to bring in your own view engine but also allows you to extend the default view engine. This means you can use any view engine you want, including Twig, Smarty, etc., or you can extend the default Leaf view engine to add your own custom features like custom directives, filters, etc.
+
+If you need to add anything new to your view layer, you can publish the view config using the `config:publish` command:
+
+```bash:no-line-numbers
+php leaf config:publish view
+```
+
+This will create a `config/view.php` file in your `app` directory where you can add your custom view configurations. For this example, we will add a new directive to the view engine:
+
+```php
+ \Leaf\Blade::class,
+
+ /*
+ |--------------------------------------------------------------------------
+ | Custom config method
+ |--------------------------------------------------------------------------
+ |
+ | Configuration for your templating engine.
+ |
+ */
+ 'config' => function (\Leaf\Blade $engine, array $config) {
+ $engine->configure($config['views'], $config['cache']);
+ },
+
+ /*
+ |--------------------------------------------------------------------------
+ | Custom render method
+ |--------------------------------------------------------------------------
+ |
+ | This render method is triggered whenever render() is called
+ | in your app if you're using a custom view engine.
+ |
+ */
+ 'render' => null,
+
+ /*
+ |--------------------------------------------------------------------------
+ | Extend view engine
+ |--------------------------------------------------------------------------
+ |
+ | Some view engines like blade allow you extend the engine to
+ | add extra functions or directives. This is just the place to
+ | do all of that. Extend is a function that accepts an instance
+ | of your view engine which you can 'extend'
+ |
+ */
+ 'extend' => null,
+];
+```
+
+We can pass a function to the `extend` key to extend the Blade view engine. Leaf will give us the instanciated view engine as the first argument, so we can use it to add our custom directive:
+
+```php
+'extend' => function (\Leaf\Blade $engine) {
+ $engine->directive('Button', function ($expression) {
+ return "$expression