From 0603a079e22e10a9c36c334e867edf5fcc1e20ad Mon Sep 17 00:00:00 2001 From: mychidarko Date: Mon, 6 Jan 2025 13:00:54 +0000 Subject: [PATCH 1/7] feat: update docs to match MVC 3.9 --- src/docs/mvc/commands.md | 35 +++++++++++++---------------------- src/docs/mvc/libraries.md | 4 ++-- 2 files changed, 15 insertions(+), 24 deletions(-) diff --git a/src/docs/mvc/commands.md b/src/docs/mvc/commands.md index 50ed38c3..e37d4ed3 100644 --- a/src/docs/mvc/commands.md +++ b/src/docs/mvc/commands.md @@ -49,7 +49,7 @@ Leaf MVC's aloe command line tool is built on top of Symfony's console component ## Manually creating a command -All commands created through the `g:command` command are stored in the `app/console` directory and are automatically loaded by Leaf MVC. However, you can also create a command manually by creating a new class that extends the `Command` class and implementing the `handle()` method just like the example above. +The `g:command` command is a shortcut to creating a new command which creates a boilerplate command class for you in the `app/console` directory. If you want to create a command manually, you can create a new class that extends the `Command` class and implements the `handle()` method. ```php register([ - ExampleCommand::class, - CachePurgeCommand::class - ]); - } -} +```bash:no-line-numbers [Leaf CLI] +leaf install aloe mvc-core +``` + +```bash:no-line-numbers [Composer] +composer require leafs/aloe leafs/mvc-core ``` +::: + ## Command Arguments 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: diff --git a/src/docs/mvc/libraries.md b/src/docs/mvc/libraries.md index 85357850..ae507c0d 100644 --- a/src/docs/mvc/libraries.md +++ b/src/docs/mvc/libraries.md @@ -14,14 +14,14 @@ php leaf config:lib That's it! A `lib` folder will be created in your application root and Leaf will now autoload any library you place in this folder. -::: info Older Leaf MVC versions + ## Creating a Library From f5d3bacd49c2f6e9060b6880b3143a5147c004d8 Mon Sep 17 00:00:00 2001 From: mychidarko Date: Mon, 6 Jan 2025 20:30:35 +0000 Subject: [PATCH 2/7] feat: add docs for new serve command --- src/docs/frontend/inertia.md | 72 +++++++++--------------- src/docs/frontend/vite.md | 104 +++++++++++++++++++---------------- src/docs/mvc/commands.md | 33 +++++++---- 3 files changed, 104 insertions(+), 105 deletions(-) diff --git a/src/docs/frontend/inertia.md b/src/docs/frontend/inertia.md index f1e343c1..fe772f1c 100644 --- a/src/docs/frontend/inertia.md +++ b/src/docs/frontend/inertia.md @@ -12,14 +12,14 @@ To get started, you can run: ::: code-group -```bash:no-line-numbers [Leaf CLI] -leaf view:install -``` - ```bash:no-line-numbers [Leaf MVC CLI] php leaf view:install ``` +```bash:no-line-numbers [Leaf CLI] +leaf view:install +``` + ::: This will prompt you to select your preferred frontend framework. You can choose from Vue, React, and Svelte. There is also support for styling with Tailwind/Bootstrap. After selecting your preferred framework, Leaf will automatically install and setup inertia for you, including examples for you to get started with. @@ -28,50 +28,26 @@ This will prompt you to select your preferred frontend framework. You can choose If you know the specific frontend framework you want to use, you can pass the `--{framework}` flag to the `view:install` command. For example, to install inertia for Vue, you can run: -```bash +```bash:no-line-numbers php leaf view:install --vue ``` ::: -To run your app, you'll need to start two servers. One to actively bundle your frontend dependencies (your framework, styles, ...): +You can then start your server which will automatically start both your Leaf server and your frontend server: ::: code-group -```bash:no-line-numbers [Leaf CLI] -leaf view:dev -``` - -```bash:no-line-numbers [npm] -npm i && npm run dev -``` - -```bash:no-line-numbers [pnpm] -pnpm i && pnpm run dev -``` - -```bash:no-line-numbers [yarn] -yarn && yarn dev +```bash:no-line-numbers [Leaf MVC CLI] +php leaf serve ``` -::: - -And then your main Leaf server which will run your app: - -::: code-group - ```bash:no-line-numbers [Leaf CLI] leaf serve ``` -```bash:no-line-numbers [Leaf MVC CLI] -php leaf serve -``` - ::: -If you want to read more on why 2 servers are necessary, you can check out the [Leaf + Vite documentation](/docs/frontend/vite#vite-other-frameworks) - ## Setting up your routes Adding Inertia to your Leaf app doesn't change the way you handle routing, it just replaces your PHP views with your frontend framework. This means you are still going to use Leaf's routing system to handle your routes: @@ -166,16 +142,16 @@ You can find more information on using Inertia with your frontend framework in t If you don't want to use the Leaf CLI, you can manually setup inertia. This guide will show you how to setup inertia with Vite and React. You can use this guide to setup inertia with any frontend framework. -### Setting up Vite +### 1. Setting up Vite To get started, you need to setup Vite. We have a Leaf plugin that takes care of a lot of the heavy lifting for you. We have a detailed guide on how to setup vite with Leaf [here](/docs/frontend/vite). -```bash +```bash:no-line-numbers npm i -D vite @leafphp/vite-plugin leaf install vite ``` -### Vite Config +### 2. Vite Config The [Leaf Vite docs](/docs/frontend/vite#vite-config) have a detailed guide on how to setup vite config files. You should however note that for the best developer experience, you should point Vite to your view directory so you can enjoy hot module reloading. @@ -201,26 +177,28 @@ leaf({ }), ``` -### Setting up Inertia +### 3. Setting up Inertia To setup inertia, you need to install the inertia package for whatever frontend framework you want to use, together with the Vite plugin for that framework. For example, if you want to use React, you should install the Inertia React package, React Vite plugin as well as React itself: -```bash +```bash:no-line-numbers npm i react react-dom @inertiajs/react @vitejs/plugin-react ``` You should also install the Leaf Inertia PHP adapter: -```bash +::: code-group + +```bash:no-line-numbers [Leaf CLI] leaf install inertia ``` -Or with composer: - -```bash +```bash:no-line-numbers [Composer] composer require leafs/inertia ``` +::: + After adding the React Vite plugin, you should add it to your vite config file: ```js{3,10} @@ -238,7 +216,7 @@ export default defineConfig({ }); ``` -### Setting up your base JavaScript file +### 4. Setting up your base JavaScript file You should create a base JavaScript file that will be used to mount your app. This file should import your CSS and other assets. For example, if you're using React, your base JavaScript file should look like this: @@ -272,17 +250,17 @@ setup({ el, App, props }) { }, ``` -### Setting up your base PHP file +### 5. Setting up your base PHP file You should create a base PHP file that will be used to render your app. By default, the Leaf Inertia PHP adapter will look for a file named `_inertia.view.php` in your views directory. You can change this by passing the path to your base PHP file to the `Inertia::setRoot` method. -```php +```php:no-line-numbers Inertia::setRoot('myfiles/_base'); ``` Since the Leaf Inertia PHP adapter is built using the [Bare UI engine](/docs/frontend/bareui), your base file needs to maintain the `.view.php` extension. For example, if you're using React, your base PHP file should look like this: -```php +```blade @@ -324,11 +302,11 @@ Since the Leaf Inertia PHP adapter is built using the [Bare UI engine](/docs/fro This might look pretty ugly, but you'll never have to touch this file again. You can also use the Leaf CLI to generate this file for you: -```bash +```bash:no-line-numbers leaf view:install --inertia ``` -### Setting up your frontend framework +### 6. Setting up your frontend framework In the setup above, we told Inertia to look for our frontend framework files in `./DIRECTORYFORCOMPONENTS/`. You should create this directory and add your frontend framework files to it. For example, if you're using React, you should create a file named `Home.jsx` in this directory: diff --git a/src/docs/frontend/vite.md b/src/docs/frontend/vite.md index 09fc8b50..c6d4b398 100644 --- a/src/docs/frontend/vite.md +++ b/src/docs/frontend/vite.md @@ -18,51 +18,13 @@ Check out these articles from SitePoint and Next JS: ## Setting Up -You can install the Vite module with the Leaf CLI: +Leaf MVC comes with Vite pre-installed, so you only need to start your server and you're good to go. If you are not using Leaf MVC, you can setup Vite using the Leaf CLI: ```bash:no-line-numbers leaf view:install --vite ``` -This command will install vite and the vite-leaf plugin, and will also install the vite module which will be used to load your assets on the server side. It will also create a vite config file at the root of your project. This config file can be used to configure vite, add plugins and more. - -If you are using Leaf MVC, all of this is done for you automatically. You just need to start your Vite server and add your assets. - -## Manually Installing Vite - -If you don't have the Leaf CLI installed, you can manually install Vite although it's a bit more complex. First, you need to install all the JavaScript dependencies: - -::: code-group - -```bash:no-line-numbers [npm] -npm i -D vite @leafphp/vite-plugin -``` - -```bash:no-line-numbers [pnpm] -pnpm i -D vite @leafphp/vite-plugin -``` - -```bash:no-line-numbers [yarn] -yarn add -D vite @leafphp/vite-plugin -``` - -::: - -After that, you need to install the server component for Vite. This will allow you to load your assets on the server side using PHP. You can install this by running: - -::: code-group - -```bash:no-line-numbers [Leaf CLI] -leaf install vite -``` - -```bash:no-line-numbers [Composer] -composer require leafs/vite -``` - -::: - -Finally, Vite requires a configuration file to run. You can create a `vite.config.js` file at the root of your project and add your configuration there. You can learn more about Vite configuration files [here](#vite-config). +This command will install vite, and the leaf-vite module which will be used to load your assets on the server side plus all vite-specific dependencies and config files. ## Loading your assets @@ -76,7 +38,7 @@ Here's an example of how you can load a CSS file: ::: code-group ```blade:no-line-numbers [Blade] -{{ vite('css/app.css') }} +@vite('css/app.css') ``` ```php:no-line-numbers [BareUI] @@ -90,7 +52,7 @@ You can also load multiple assets at once by passing in an array of assets: ::: code-group ```blade:no-line-numbers [Blade] -{{ vite(['app.css', 'app.js']) }} +@vite(['app.css', 'app.js']) ``` ```php:no-line-numbers [BareUI] @@ -137,7 +99,23 @@ Unlike the `vite.config.js` file, this configuration is done in PHP and is compl ## Running Vite -Vite comes with a development server that you can use to serve your frontend assets. This is a bit different from the traditional way of serving assets with PHP because you need to run a separate server for your assets. You can start your Vite server by running: +Vite comes with a development server that you can use to serve your frontend assets which is separate from your PHP server. If you use Leaf MVC or the Leaf CLI, this server will be automatically fired up when you run the serve command: + +::: code-group + +```bash:no-line-numbers [Leaf MVC CLI] +php leaf serve +``` + +```bash:no-line-numbers [Leaf CLI] +leaf serve +``` + +::: + +::: details Running Vite manually + +If you are not using Leaf MVC, you need to start the Vite server manually in a separate terminal process: ::: code-group @@ -157,11 +135,9 @@ pnpm i && pnpm run dev yarn && yarn dev ``` -::: - This will install the necessary dependencies and start your Vite server. You don't need to do anything with the Vite server, just keep it running in the background and Leaf will take care of the rest. -**You need to keep the Vite server running in a separate terminal window while you work on your project.** +::: ## Adding Aliases @@ -192,3 +168,39 @@ export default defineConfig({ ## Vite + other frameworks Using a combination of Leaf and Vite, you can use React with your favourite frontend technologies like React, Vue and Svelte. We've added a guide to setting up frontend frameworks using Inertia [over here](/docs/frontend/inertia). + +## Manually Installing Vite + +If you don't have the Leaf CLI installed, you can manually install Vite although it's a bit more complex. First, you need to install all the JavaScript dependencies: + +::: code-group + +```bash:no-line-numbers [npm] +npm i -D vite @leafphp/vite-plugin +``` + +```bash:no-line-numbers [pnpm] +pnpm i -D vite @leafphp/vite-plugin +``` + +```bash:no-line-numbers [yarn] +yarn add -D vite @leafphp/vite-plugin +``` + +::: + +After that, you need to install the server component for Vite. This will allow you to load your assets on the server side using PHP. You can install this by running: + +::: code-group + +```bash:no-line-numbers [Leaf CLI] +leaf install vite +``` + +```bash:no-line-numbers [Composer] +composer require leafs/vite +``` + +::: + +Finally, Vite requires a configuration file to run. You can create a `vite.config.js` file at the root of your project and add your configuration there. You can learn more about Vite configuration files [here](#vite-config). diff --git a/src/docs/mvc/commands.md b/src/docs/mvc/commands.md index e37d4ed3..7a12c032 100644 --- a/src/docs/mvc/commands.md +++ b/src/docs/mvc/commands.md @@ -82,23 +82,32 @@ class CachePurgeCommand extends Command } ``` -Be sure to keep your command class in the `App\Console` namespace and extend the `Command` class and in the `app/console` directory. Once you've created your command, Leaf MVC will automatically load it when you run the `php leaf` console. +If you are using Leaf MVC v3.8 and above, the command is automatically loaded by Leaf MVC, but Leaf MVC v3.7 and below require you to register your new command in the `app/console/Commands.php` file. -::: details Commands not auto-loading? -If your command is not auto-loading, make sure you have the latest versions of MVC Core and Aloe installed. - -::: code-group +```php +register([ + ExampleCommand::class, + CachePurgeCommand::class + ]); + } +} ``` -::: - ## Command Arguments 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: From 006cd52427aa9d7db5686e560ce807d887c6ab93 Mon Sep 17 00:00:00 2001 From: mychidarko Date: Mon, 6 Jan 2025 20:46:18 +0000 Subject: [PATCH 3/7] feat: update view:install and g:template docs --- src/docs/frontend/inertia.md | 55 +++++++++++++++++------------------- 1 file changed, 26 insertions(+), 29 deletions(-) diff --git a/src/docs/frontend/inertia.md b/src/docs/frontend/inertia.md index fe772f1c..47052b38 100644 --- a/src/docs/frontend/inertia.md +++ b/src/docs/frontend/inertia.md @@ -6,48 +6,28 @@ In short, Inertia let's you use your favourite frontend framework together with ## Setting Up -We've simplified the whole setup process into one command for you. Whether you are using Leaf MVC or just Leaf, you can use the CLI to scaffold a basic UI integration using your preferred frontend tooling. +We've simplified the whole setup process into one command for you. Whether you are using Leaf MVC or just Leaf, you can use the CLI to scaffold a basic UI integration using your preferred frontend tooling. Simply run the `view:install` command with the name of the frontend framework you want to use. To get started, you can run: ::: code-group ```bash:no-line-numbers [Leaf MVC CLI] -php leaf view:install -``` - -```bash:no-line-numbers [Leaf CLI] -leaf view:install -``` - -::: - -This will prompt you to select your preferred frontend framework. You can choose from Vue, React, and Svelte. There is also support for styling with Tailwind/Bootstrap. After selecting your preferred framework, Leaf will automatically install and setup inertia for you, including examples for you to get started with. - -::: tip view:install - -If you know the specific frontend framework you want to use, you can pass the `--{framework}` flag to the `view:install` command. For example, to install inertia for Vue, you can run: - -```bash:no-line-numbers php leaf view:install --vue -``` - -::: - -You can then start your server which will automatically start both your Leaf server and your frontend server: - -::: code-group - -```bash:no-line-numbers [Leaf MVC CLI] -php leaf serve +php leaf view:install --react +php leaf view:install --svelte ``` ```bash:no-line-numbers [Leaf CLI] -leaf serve +leaf view:install --vue +leaf view:install --react +leaf view:install --svelte ``` ::: +This will automatically set up everything you need to get started with Inertia and your preferred frontend framework. You can then start your development server and start building your app. + ## Setting up your routes Adding Inertia to your Leaf app doesn't change the way you handle routing, it just replaces your PHP views with your frontend framework. This means you are still going to use Leaf's routing system to handle your routes: @@ -101,7 +81,7 @@ export default function Home({ name }) { } ``` -```jsx [Home.vue] +```vue [Home.vue] -Blade is a templating engine included with Laravel that helps you create dynamic views easily. Unlike other templating engines, Blade allows you to use regular PHP code inside your templates together with all the goodness it offers you. Behind the scenes, Blade templates are turned into plain PHP and cached, so they run quickly without slowing down your app. Blade files use the `.blade.php` extension to distinguish them from regular PHP files. +Blade is Laravel's own templating engine that makes creating dynamic views easy. It lets you mix regular PHP code with its own features for more flexibility, has a clean syntax and caches your views for faster performance. -Leaf Blade is a port of the [jenssegers/blade](https://github.com/jenssegers/blade) package that allows you to use blade templates in your Leaf PHP projects. +Leaf Blade is an adaptation of the original Blade package that allows you to use Blade templates in your Leaf PHP projects powered by [jenssegers/blade](https://github.com/jenssegers/blade). @@ -27,13 +27,7 @@ This video by The Net Ninja will help you get started with blade. ## Setting Up -::: info Blade + Leaf MVC - -Blade comes with Leaf MVC out of the box, fully configured and ready to use, so you can skip this section if you're using Leaf MVC. - -::: - -You can install Leaf Blade using the Leaf CLI: +Blade comes with Leaf MVC out of the box, fully configured and ready to use, however, if you're using Leaf on its own, you can install Blade using the Leaf CLI or Composer. ::: code-group @@ -47,7 +41,9 @@ composer require leafs/blade ::: -After this, you just need to inform Leaf of Blade's existence: +::: details Configuring your paths + +After installing Blade in your Leaf app, you just need to inform Leaf of Blade's existence: ```php:no-line-numbers app()->attachView(Leaf\Blade::class); @@ -62,6 +58,10 @@ app()->blade()->configure([ ]); ``` +Once again, this is only necessary if you're using Leaf on its own. If you're using Leaf MVC, Blade is already set up for you. + +::: + Magic! You can now use Blade to create and render your views. ## Creating Blade Views @@ -99,11 +99,13 @@ echo app()->blade()->render('hello', ['name' => 'Michael']); This will render the `hello.blade.php` view and pass in a variable called `name` with the value `Michael`. When you open the view in your browser, you should see a big "Hello, Michael" on your screen. - + +