From 1a574489462694768d05c001bf11d245836c7a40 Mon Sep 17 00:00:00 2001 From: mychidarko Date: Wed, 4 Dec 2024 22:51:52 +0000 Subject: [PATCH 1/5] feat: add warnings for non-normal behaviour --- src/docs/database/builder.md | 22 ++++++++++++++-------- 1 file changed, 14 insertions(+), 8 deletions(-) diff --git a/src/docs/database/builder.md b/src/docs/database/builder.md index 74b0af80..d3d3441b 100644 --- a/src/docs/database/builder.md +++ b/src/docs/database/builder.md @@ -6,7 +6,7 @@ Although you can write raw queries using the `query()` method, there's no fun in This is something you would usually want to do outside of your application, but there are a few rare cases where you might want to create a database from within your application. Leaf DB provides a `create()` method that allows you to do just that. -```php +```php:no-line-numbers db()->create('dbname')->execute(); ``` @@ -26,7 +26,7 @@ db() Dropping a database is the opposite of creating one. It deletes the database and all its contents. Leaf DB provides a `drop()` method that allows you to do this. -```php +```php:no-line-numbers db()->drop('dbname')->execute(); ``` @@ -40,13 +40,13 @@ This method needs the name of the table you want to add data to, like "users", a Here's an example: -```php +```php:no-line-numbers db()->insert('users')->params(['username' => 'mychi']); ``` This is equivalent to the following SQL query: -```sql +```sql:no-line-numbers INSERT INTO users (username) VALUES ('mychi') ``` @@ -89,17 +89,19 @@ db()->insert('users')->params(['username' => 'mychi'])->execute(); $lastId = db()->lastInsertId(); ``` +Note that this may not work correctly if your database uses non-auto-incrementing IDs like UUIDs or ULIDs. + ## Reading data from a database Reading from a database means retrieving data stored in a table. Leaf DB provides a `select()` method that allows you to build a query to retrieve data from a table. The `select()` method takes the name of the table you want to read from as its argument. -```php +```php:no-line-numbers db()->select('users')->all(); ``` This will return all the rows in the users table. You can also specify the columns you want to return by passing them as the second argument to the `select()` method. -```php +```php:no-line-numbers db()->select('users', 'name, created_at')->all(); ``` @@ -172,7 +174,7 @@ db() Almost every database table has an `id` column that uniquely identifies each row. Leaf DB provides a `find()` method that allows you to retrieve a row by its `id`. -```php +```php:no-line-numbers db()->select('users')->find(1); ``` @@ -209,7 +211,7 @@ Deleting data from a database works by finding the data you want to delete and t Here's an example: -```php +```php:no-line-numbers db()->delete('users')->execute(); // careful now 🙂 ``` @@ -259,6 +261,10 @@ if ($success) { This is useful especially when you have a set of queries that rely on third party influence. +::: warning Rollback not working +Transactions will only work correctly if your queries use Leaf DB. This is because your queries need to use the same database connection to be able to be rolled back. This means you can't use transactions with your Leaf MVC models at the moment, but this may change in the future. +::: + ## 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. From 539416cc8d577143fbea1a4bbf1ab8d378bada01 Mon Sep 17 00:00:00 2001 From: mychidarko Date: Thu, 5 Dec 2024 21:03:53 +0000 Subject: [PATCH 2/5] feat: add new Leaf MVC docs --- src/docs/database/builder.md | 19 +++++++++++++++ src/docs/database/redis.md | 33 ++++++++++++++++++++----- src/docs/frontend/blade.md | 47 ++++++++++++++++++++++++++++++++++-- src/docs/mvc/commands.md | 2 +- src/docs/mvc/console.md | 12 ++++++--- 5 files changed, 100 insertions(+), 13 deletions(-) diff --git a/src/docs/database/builder.md b/src/docs/database/builder.md index d3d3441b..d00f661f 100644 --- a/src/docs/database/builder.md +++ b/src/docs/database/builder.md @@ -348,6 +348,25 @@ db() ->all(); ``` +## Counting results + +You can count the number of results returned by a query using the `count()` method. + +```php +db() + ->select('users') + ->count(); +``` + +Or even with complex queries: + +```php +db() + ->select('users') + ->where('age', '>', 20) + ->count(); +``` + ## Error Handling There are lots of times where your query might fail. This could be because of a syntax error, a missing table, or a missing column. Leaf DB provides an `errors()` method that allows you to get the error message if your query fails. diff --git a/src/docs/database/redis.md b/src/docs/database/redis.md index 532d3caa..889b805e 100644 --- a/src/docs/database/redis.md +++ b/src/docs/database/redis.md @@ -43,7 +43,7 @@ composer require leafs/redis Once that's done, we can start using Leaf Redis in our Leaf application. Just like any other database, we need to initialize a connection to Redis before we can start using it. -```php +```php:no-line-numbers redis()->connect(); ``` @@ -53,7 +53,26 @@ This will initialize a new Redis connection. From there, you can start storing a If you're using Leaf MVC, you can add on some extra features to your setup. Leaf Redis comes with a few commands that you can attach to your Aloe CLI. You can do this by heading over to the `app/console/Commands.php` file in your Leaf MVC app and adding the following line to the return array. -```php +::: code-group + +```php [Leaf MVC 3.8 and above] +/* +|-------------------------------------------------------------------------- +| Load Leaf configuration +|-------------------------------------------------------------------------- +| +| Leaf MVC allows you to customize Leaf and it's modules using +| configuration files defined in the config folder. This line +| loads the configuration files and makes them available to +| your application. +| +*/ +Leaf\Core::loadConsole([ + Leaf\Redis::commands() // [!code ++] +]); +``` + +```php [Leaf MVC 3.7 and below] register([ ExampleCommand::class, - \Leaf\Redis::commands() // [!code ++] + Leaf\Redis::commands() // [!code ++] ]); } } ``` +::: + Once you've done that, you should have access to a bunch of new commands from Leaf Redis. The available commands are: -```bash +```bash:no-line-numbers redis redis:install Create leaf redis config and .env variables redis:server Start redis server @@ -212,7 +233,7 @@ redis()->connect([ You can check if your Redis connection is working by using the `ping()` method. The `ping()` method returns a string with the message "PONG" if the connection is successful. -```php +```php:no-line-numbers echo redis()->ping(); ``` @@ -220,7 +241,7 @@ echo redis()->ping(); You can set values in Redis using the `set()` method. The `set()` method takes in a key and a value. -```php +```php:no-line-numbers redis()->set('name', 'Michael'); ``` diff --git a/src/docs/frontend/blade.md b/src/docs/frontend/blade.md index d0644260..70c3807b 100644 --- a/src/docs/frontend/blade.md +++ b/src/docs/frontend/blade.md @@ -10,6 +10,8 @@ Blade is a templating engine included with Laravel that helps you create dynamic 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. + + ::: details New to Blade? This video by The Net Ninja will help you get started with blade. @@ -27,7 +29,7 @@ This video by The Net Ninja will help you get started with blade. ::: info Blade + Leaf MVC -Blade comes with Leaf MVC out of the box, fully configured and ready to use. However, if you're using Leaf Core, you'll need to set up Blade yourself. +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. ::: @@ -85,7 +87,7 @@ Blade views are a pretty sweet mixture of HTML, PHP, and clean syntax. You can c ::: -This should look pretty familiar if you know HTML (of course you do). The only difference is the `{{ $name }}` part. This is Blade's way of creating a variable in your view. When you render this view, Blade will allow you pass in a variable called `$name` and it will be displayed in place of `{{ $name }}`. Let's see how you can render this view. +This should look pretty familiar if you know HTML (of course you do). The only difference is the `{{ $name }}` part. This is Blade's way of creating a variable in your view. When you render this view, Blade will allow you pass in a variable called `$name` and it will be displayed in place of `{{ $name }}`. Let's see how you can render this view. ## Rendering Blade Views @@ -97,6 +99,47 @@ 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. + + ## Extending Blade Views Blade allows you to define custom directives using the `directive()` method. When the Blade compiler encounters the custom directive, it will call the provided callback with the expression that the directive contains. The callback is free to return the value of its contents however you like: diff --git a/src/docs/mvc/commands.md b/src/docs/mvc/commands.md index d0d30534..e13a3fc3 100644 --- a/src/docs/mvc/commands.md +++ b/src/docs/mvc/commands.md @@ -82,7 +82,7 @@ class CachePurgeCommand extends Command } ``` -You can register this component by heading over to the `app/console/commands.php` file and adding the command to the `register()` method. +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 ```php Date: Thu, 5 Dec 2024 21:07:21 +0000 Subject: [PATCH 3/5] fix: update text response --- src/docs/http/response.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/docs/http/response.md b/src/docs/http/response.md index f99a525a..947ec206 100644 --- a/src/docs/http/response.md +++ b/src/docs/http/response.md @@ -54,7 +54,7 @@ Also, Leaf's response object provides a clean and consistent API for creating re ## Plain text responses -Plain text responses can be created using the `text()` method. This method accepts 2 parameters: +Plain text responses can be created using the `plain()` method. This method accepts 2 parameters: - a string as text to output - an optional status code (defaults to 200/OK) @@ -62,11 +62,11 @@ Plain text responses can be created using the `text()` method. This method accep ::: code-group ```php [Functional Mode] -response()->text('Hello, world!'); +response()->plain('Hello, world!'); ``` ```php [Leaf Instance] -$app->response()->text('Hello, world!'); +$app->response()->plain('Hello, world!'); ``` ::: From 0ff05cf7d5898976e0986d60ae25c39c878beebc Mon Sep 17 00:00:00 2001 From: mychidarko Date: Thu, 5 Dec 2024 21:25:19 +0000 Subject: [PATCH 4/5] feat: add custom response documentation --- src/docs/http/response.md | 36 ++++++++++++++++++++++++++++++++++-- 1 file changed, 34 insertions(+), 2 deletions(-) diff --git a/src/docs/http/response.md b/src/docs/http/response.md index 947ec206..3e79f7a7 100644 --- a/src/docs/http/response.md +++ b/src/docs/http/response.md @@ -61,11 +61,11 @@ Plain text responses can be created using the `plain()` method. This method acce ::: code-group -```php [Functional Mode] +```php:no-line-numbers [Functional Mode] response()->plain('Hello, world!'); ``` -```php [Leaf Instance] +```php:no-line-numbers [Leaf Instance] $app->response()->plain('Hello, world!'); ``` @@ -258,6 +258,38 @@ $app->response()->xml('withHeader([ + 'Content-Type' => 'application/pdf', + 'Content-Length' => $dataLength, + 'Content-Disposition' => "inline; filename=\"$filename\"" + ]) + ->custom($rawData); +``` + +```php:no-line-numbers [Leaf Instance] +$app + ->response() + ->withHeader([ + 'Content-Type' => 'application/pdf', + 'Content-Length' => $dataLength, + 'Content-Disposition' => "inline; filename=\"$filename\"" + ]) + ->custom($rawData); +``` + +::: + ## Headers Headers are a way for your server to send additional information along with your request. This information can be anything from the type of content you're sending back, to the status code of your response, to the type of server you're using. From 7e50db489501632e222b9c75815226695bbb4a86 Mon Sep 17 00:00:00 2001 From: mychidarko Date: Thu, 5 Dec 2024 21:26:37 +0000 Subject: [PATCH 5/5] feat: add custom response documentation --- src/docs/http/response.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/docs/http/response.md b/src/docs/http/response.md index 3e79f7a7..61534501 100644 --- a/src/docs/http/response.md +++ b/src/docs/http/response.md @@ -260,7 +260,7 @@ $app->response()->xml(' $dataLength, 'Content-Disposition' => "inline; filename=\"$filename\"" ]) - ->custom($rawData); + ->echo($rawData); ``` ```php:no-line-numbers [Leaf Instance] @@ -285,7 +285,7 @@ $app 'Content-Length' => $dataLength, 'Content-Disposition' => "inline; filename=\"$filename\"" ]) - ->custom($rawData); + ->echo($rawData); ``` :::