Issue #110: update book tutorial #112

Howriq · 2025-05-12T20:53:55Z

No description provided.

Signed-off-by: horea <[email protected]>

alexmerlin

To be continued...

docs/book/v5/tutorials/create-book-module.md

docs/book/v6/tutorials/create-book-module.md

Signed-off-by: horea <[email protected]>

alexmerlin

In ReleaseDateInput, replace:
'message' => sprintf(Message::INVALID_VALUE, 'releaseDate'),
with:
'message' => Message::INVALID_VALUE,
and remove use function sprintf;.
The migrations diff command is outdated, replace it with:

php ./vendor/bin/doctrine-migrations diff

The path mentioned in this sentence has changed in 6.0:

This will check for differences between your entities and database structure and create migration files if necessary, in data/doctrine/migrations.

Version 6.0 stores migrations in the Core module under the following path:
src/Core/src/App/src/Migration

The migrations run command should also be updated:

php ./vendor/bin/doctrine-migrations migrate

Rename across the document GetBookHandler to GetBookResourceHandler
Rename across the document PostBookHandler to PostBookResourceHandler

so that they follow our naming convention.

docs/book/v6/tutorials/create-book-module.md

docs/book/v6/extended-features/email.md

Signed-off-by: horea <[email protected]>

docs/book/v6/tutorials/create-book-module.md

alexmerlin · 2025-05-15T07:55:05Z

docs/book/v6/tutorials/create-book-module.md

-        ];
-    }
+        $routeCollector->post('/book', PostBookHandler::class, 'book::create-book');
+        $routeCollector->get('/book/' . $uuid, GetBookHandler::class, 'book::view-book');


Suggested change

$routeCollector->get('/book/' . $uuid, GetBookHandler::class, 'book::view-book');

$routeCollector->get('/book/' . $uuid, GetBookResourceHandler::class, 'book::view-book');

Because:

Rename across the document GetBookHandler to GetBookResourceHandler

alexmerlin · 2025-05-15T07:55:50Z

docs/book/v6/tutorials/create-book-module.md

-            ],
-        ];
-    }
+        $routeCollector->post('/book', PostBookHandler::class, 'book::create-book');


Suggested change

$routeCollector->post('/book', PostBookHandler::class, 'book::create-book');

$routeCollector->post('/book', PostBookResourceHandler::class, 'book::create-book');

Because:

Rename across the document PostBookHandler to PostBookResourceHandler

alexmerlin · 2025-05-15T08:01:22Z

docs/book/v6/tutorials/create-book-module.md

+    │   └── src/
+    │       ├── Collection/
+    │       │   └── BookCollection.php
+    │       ├── Entity/


Remove node - the Book entity is in the Core module.

docs/book/v6/tutorials/create-book-module.md

alexmerlin · 2025-05-15T08:15:48Z

docs/book/v6/tutorials/create-book-module.md

-> Make sure you read and understand the rbac documentation.
-
-It's time to update the `ConfigProvider` with all the necessary configuration needed, so the above files to work properly like dependency injection, aliases, doctrine mapping and so on.
+After we have the handler, we need to register some routes in the `RoutesDelegator` using our new grouping method, the same we created when we registered the module.


Suggested change

After we have the handler, we need to register some routes in the `RoutesDelegator` using our new grouping method, the same we created when we registered the module.

After we have the handler, we need to register some routes in the `RoutesDelegator`, the same we created when we registered the module.

We abandoned route groups for this tutorial.

alexmerlin · 2025-05-15T08:18:49Z

docs/book/v6/tutorials/create-book-module.md


-In `src/Book/src` we will create 2 php files: `RoutesDelegator.php` and `ConfigProvider.php`. This files will be updated later with all needed configuration.
+In `src/Book/src` we will create 2 PHP files: `RoutesDelegator.php` and `ConfigProvider.php`. These files contain the necessary configurations.

 * `src/Book/src/RoutesDelegator.php`


This section is duplicate - you are creating the RoutesDelegator towards the end of the tutorial.
Let's keep only that one!

alexmerlin · 2025-05-15T08:22:27Z

docs/book/v6/tutorials/create-book-module.md

+* `src/Book/src/Service/BookService.php` – is a class or component responsible for performing a specific task or providing functionality to other parts of the application
+* `src/Core/src/Book/src/ConfigProvider.php` – is a class that provides configuration for Doctrine ORM
+* `src/Core/src/Book/src/Entity/Book.php` – an entity refers to a PHP class that represents a persistent object or data structure
+* `src/Core/src/Book/src/Repository/BookRepository.php` – a repository is a class responsible for querying and retrieving entities from the database

 ## Creating and configuring the module


This section could be a bit confusing for devs.
You instruct them to create a ConfigProvider with classes which don't exist yet - better leave it for when all the classes have been created.
We should keep here only the instructions for creating the directory structure and move the creation of the two ConfigProviders and the RouteDelegator to the end of the File creation and contents section.

alexmerlin · 2025-05-15T08:24:05Z

docs/book/v6/tutorials/create-book-module.md

+                ],
+            ],
+        ];
+    }
 }
 ```

 ### Registering the module


This section should also be moved further down to the point where the ConfigProvider has already been created.

alexmerlin · 2025-05-15T08:25:03Z

docs/book/v6/tutorials/create-book-module.md


-To keep things simple in this tutorial our book will have 3 properties: `name`, `author` and `release date`.
+To keep things simple in this tutorial, our book will have 3 properties: `name`, `author` and `release date`.


Suggested change

To keep things simple in this tutorial, our book will have 3 properties: `name`, `author` and `release date`.

To keep things simple in this tutorial, our book will have 3 properties: `name`, `author` and `releaseDate`.

alexmerlin · 2025-05-15T08:58:51Z

docs/book/v6/tutorials/create-book-module.md

@@ -460,29 +555,29 @@ class ReleaseDateInput extends Input

        $this->getValidatorChain()
            ->attachByName(Date::class, [
-                'message' => sprintf(Message::INVALID_VALUE, 'releaseDate'),
+                'message' => Message::INVALID_VALUE,


Suggested change

'message' => Message::INVALID_VALUE,

'message' => Message::invalidValue('releaseDate'),

Signed-off-by: horea <[email protected]>

alexmerlin

After this, these steps will have to be tested in version 6.0 of Dotkernel API.

alexmerlin · 2025-05-16T09:42:50Z

docs/book/v6/tutorials/create-book-module.md

 namespace Api\Book;

-use Api\Book\Handler\BookHandler;
+use Api\Book\Handler\GetBookCollectionHandler;
+use Api\Book\Handler\GetBookHandler;


Suggested change

use Api\Book\Handler\GetBookHandler;

use Api\Book\Handler\GetBookResourceHandler;

alexmerlin · 2025-05-16T09:46:32Z

docs/book/v6/tutorials/create-book-module.md


 ## File creation and contents

+In `src` and `src/Core/src` folders we will create one `Book` folder and in those we will create the `src` folder.
+So the final structure will be like this: `src/Book/src` and `src/Core/src/Book/src`.
+
 Each file below have a summary description above of what that file does.


Suggested change

Each file below have a summary description above of what that file does.

Devs just read through these descriptions, no need to do it again.

alexmerlin · 2025-05-16T09:57:19Z

docs/book/v6/tutorials/create-book-module.md

@@ -248,26 +165,22 @@ class Book extends AbstractEntity

 ```

-* `src/Book/src/Repository/BookRepository.php`
+* `src/Core/src/Book/src/Repository/BookRepository.php`


Repository structure in general has changed in 6.0.
Having a saveBook method is correct, but note that there is a generic saveResource method.
getBooks should not return a Query instance, but a QueryBuilder, see example here.

alexmerlin · 2025-05-16T10:15:19Z

docs/book/v6/tutorials/create-book-module.md

 use DateTimeImmutable;
+use Dot\DependencyInjection\Attribute\Inject;
+use Exception;

 class BookService implements BookServiceInterface


This needs some refactoring, see AdminService in 6.0 for example.
Then adapt BookServiceInterface.

alexmerlin · 2025-05-16T10:26:58Z

docs/book/v6/tutorials/create-book-module.md

 ```

+That's it. The module is now registered.
+
+We need to configure access to the newly created endpoints, add `books::list-books`, `book::view-book` and `book::create-book` to the authorization rbac array, under the `UserRole::ROLE_GUEST` key.


Suggested change

We need to configure access to the newly created endpoints, add `books::list-books`, `book::view-book` and `book::create-book` to the authorization rbac array, under the `UserRole::ROLE_GUEST` key.

We need to configure access to the newly created endpoints.

Open `config/autoload/authorization.global.php` and append the below route names to the `UserRoleEnum::Guest->value` key:

- `books::list-books`

- `book::view-book`

- `book::create-book`

alexmerlin · 2025-05-16T10:28:35Z

docs/book/v6/tutorials/create-book-module.md

+
+We need to configure access to the newly created endpoints, add `books::list-books`, `book::view-book` and `book::create-book` to the authorization rbac array, under the `UserRole::ROLE_GUEST` key.
+> Make sure you read and understand the rbac [documentation](https://docs.dotkernel.org/dot-rbac-guard/v4/configuration/).
+
 ## Migrations

 We created the `Book` entity, but we didn't create the associated table for it.


In this section:

fix typo shel

replace php bin/doctrine orm:validate-schema with php ./bin/doctrine orm:validate-schema

Signed-off-by: horea <[email protected]>

Issue dotkernel#110: update book tutorial

9757b37

Signed-off-by: horea <[email protected]>

Howriq requested a review from alexmerlin May 12, 2025 20:55

alexmerlin requested changes May 13, 2025

View reviewed changes

Howriq linked an issue May 13, 2025 that may be closed by this pull request

update book tutorial #110

Open

Howriq added 4 commits May 13, 2025 13:07

Issue dotkernel#110: update book tutorial

b473f4c

Signed-off-by: horea <[email protected]>

Issue dotkernel#110: update book tutorial

564d9bf

Signed-off-by: horea <[email protected]>

Issue dotkernel#110: update book tutorial

bd407bf

Signed-off-by: horea <[email protected]>

Issue dotkernel#110: update book tutorial

b1789bd

Signed-off-by: horea <[email protected]>

Howriq linked an issue May 13, 2025 that may be closed by this pull request

version 6: how to send an email and parse the content #104

Open

alexmerlin requested changes May 14, 2025

View reviewed changes

alexmerlin reviewed May 14, 2025

View reviewed changes

docs/book/v6/tutorials/create-book-module.md Outdated Show resolved Hide resolved

alexmerlin reviewed May 14, 2025

View reviewed changes

docs/book/v6/extended-features/email.md Outdated Show resolved Hide resolved

Howriq added 3 commits May 14, 2025 12:59

Issue dotkernel#110: update book tutorial

cc62378

Signed-off-by: horea <[email protected]>

Issue dotkernel#110: update book tutorial

44cd800

Signed-off-by: horea <[email protected]>

Issue dotkernel#110: update book tutorial

ae15291

Signed-off-by: horea <[email protected]>

Howriq requested a review from alexmerlin May 14, 2025 10:28

alexmerlin requested changes May 15, 2025

View reviewed changes

alexmerlin reviewed May 15, 2025

View reviewed changes

alexmerlin removed a link to an issue May 15, 2025

version 6: how to send an email and parse the content #104

Open

Issue dotkernel#110: update book tutorial

dec0212

Signed-off-by: horea <[email protected]>

Howriq requested a review from alexmerlin May 16, 2025 09:06

alexmerlin requested changes May 16, 2025

View reviewed changes

Issue dotkernel#110: update book tutorial

721a2a7

Signed-off-by: horea <[email protected]>

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Issue #110: update book tutorial #112

Issue #110: update book tutorial #112

Howriq commented May 12, 2025

alexmerlin left a comment

alexmerlin left a comment

alexmerlin May 15, 2025

alexmerlin May 15, 2025

alexmerlin May 15, 2025

alexmerlin May 15, 2025

alexmerlin May 15, 2025

alexmerlin May 15, 2025

alexmerlin May 15, 2025

alexmerlin May 15, 2025

alexmerlin May 15, 2025

alexmerlin left a comment

alexmerlin May 16, 2025

alexmerlin May 16, 2025 •

edited

Loading

alexmerlin May 16, 2025

alexmerlin May 16, 2025

alexmerlin May 16, 2025

alexmerlin May 16, 2025

	$routeCollector->get('/book/' . $uuid, GetBookHandler::class, 'book::view-book');
	$routeCollector->get('/book/' . $uuid, GetBookResourceHandler::class, 'book::view-book');

	$routeCollector->post('/book', PostBookHandler::class, 'book::create-book');
	$routeCollector->post('/book', PostBookResourceHandler::class, 'book::create-book');

	After we have the handler, we need to register some routes in the `RoutesDelegator` using our new grouping method, the same we created when we registered the module.
	After we have the handler, we need to register some routes in the `RoutesDelegator`, the same we created when we registered the module.


		To keep things simple in this tutorial our book will have 3 properties: `name`, `author` and `release date`.
		To keep things simple in this tutorial, our book will have 3 properties: `name`, `author` and `release date`.

	'message' => Message::INVALID_VALUE,
	'message' => Message::invalidValue('releaseDate'),

	use Api\Book\Handler\GetBookHandler;
	use Api\Book\Handler\GetBookResourceHandler;

Issue #110: update book tutorial #112

Are you sure you want to change the base?

Issue #110: update book tutorial #112

Conversation

Howriq commented May 12, 2025

alexmerlin left a comment

Choose a reason for hiding this comment

alexmerlin left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

alexmerlin left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

alexmerlin May 16, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

alexmerlin May 16, 2025 •

edited

Loading