diff --git a/docs/book/v1/how-tos/routing.md b/docs/book/v1/how-tos/routing.md index 34c0d04..f9f9e81 100644 --- a/docs/book/v1/how-tos/routing.md +++ b/docs/book/v1/how-tos/routing.md @@ -19,23 +19,30 @@ Those are being declared in the file `config/autoload/local.php` in the followin ``` In this case `page` represents the module and `'about' => 'about'` represents the page slug and its assigned `.twig` template. -To clarify, this creates a route called `page.about` in the `page` module, it loads the template file `src/Page/templates/page/about.html.twig` and can be accessed at `/page/about`. -With each request, when matching one of these routes, the `PageHandler` will detect the current route name and render the matching template. +To clarify, this creates a route called `page::about` in the `page` module, it loads the template file `src/Page/templates/page/about.html.twig` and can be accessed at `/page/about`. +The separator between the prefix and the template name is a double colon, so `url('page::about')` resolves, while `url('page.about')` throws. +With each request, when matching one of these routes, the `GetPageViewHandler` will detect the current route name and render the matching template. ### Manipulating the declared routes and modules -Each module has a `RoutesDelegator.php` file (ex. `src/Page/src/RoutesDelegator.php`). -In this file we are retrieving the application config from the container and we loop over each module and their assigned routes. +Each module registers its routes in a `RoutesDelegator.php` file, and the two modules do this differently. +`src/Page/src/RoutesDelegator.php` retrieves the application config from the container and loops over each prefix and its assigned routes: ```php $routes = $container->get('config')['routes'] ?? []; - foreach ($routes as $moduleName => $moduleRoutes) { + foreach ($routes as $prefix => $moduleRoutes) { foreach ($moduleRoutes as $routeUri => $templateName) { $app->get( - sprintf('/%s/%s', $moduleName, $routeUri), - [PageHandler::class], - sprintf('%s::%s', $moduleName, $templateName) + sprintf('/%s/%s', $prefix, $routeUri), + GetPageViewHandler::class, + sprintf('%s::%s', $prefix, $templateName) ); } } ``` + +`src/App/src/RoutesDelegator.php` declares no config-driven routes at all — it registers a single static route for the home page: + +```php + $app->get('/', [GetIndexViewHandler::class], 'app::index'); +``` diff --git a/docs/book/v1/introduction/file-structure.md b/docs/book/v1/introduction/file-structure.md index 1f9ea26..d944110 100644 --- a/docs/book/v1/introduction/file-structure.md +++ b/docs/book/v1/introduction/file-structure.md @@ -10,14 +10,32 @@ When using Dotkernel Light, the following structure is installed by default: ## Special purpose folders -* `.github` - containes workflow files -* `.laminas-ci` - contains laminas-ci workflow files +* `.github` - contains the GitHub Actions workflow files + +## Root files + +These files sit at the root of the repository: + +* `.gitattributes` - normalises line endings, and marks which files Git treats as binary or diffs as markdown +* `CHANGELOG.md` - the release history +* `LICENSE` - the project licence +* `OSSMETADATA` - declares the open source lifecycle state of the project +* `README.md` - the project readme +* `SECURITY.md` - the supported versions and the process for reporting a vulnerability +* `composer.json` - PHP dependencies, autoloading, and the `composer` scripts listed throughout this documentation +* `package.json` - front-end dependencies, and the `npm run build` and `npm run watch` scripts +* `phpcs.xml` - PHP_CodeSniffer configuration, used by `composer cs-check` and `composer cs-fix` +* `phpstan.neon` - PHPStan configuration, used by `composer static-analysis` +* `phpunit.xml` - PHPUnit configuration, used by `composer test` +* `renovate.json` - Renovate configuration for automated dependency updates +* `vite.config.js` - the Vite build configuration; see [Manage Assets](../how-tos/manage-assets.md) ## `bin` folder This folder contents are -* `clear-config-cache.php` - Removes the config cache file `data/cache/config-cache.php`; available only when development mode is enabled +* `clear-config-cache.php` - Removes the config cache file `data/cache/config-cache.php`; also available as `composer clear-config-cache` +* `composer-post-install-script.php` - Runs automatically on Composer's `post-update-cmd` hook, and copies the distributed local configuration template in `config/autoload/` into place unless that file already exists ## `config` folder @@ -54,8 +72,8 @@ When you access the application from the browser, (if not already created) a new This folder contains all publicly available assets and serves as the entry point of the application: -* `css` and `js` - Contains the css and js file(s) generated by the webpack (npm) from the assets folder -* `fonts` and `images` - Contain the font and image file(s) copied by the webpack (npm) from the assets folder +* `css` and `js` - Contain the css and js file(s) built by Vite from the assets folder +* `fonts` and `images` - Contain the font and image file(s) copied by Vite from the assets folder * `.htaccess` - server configuration file used by Apache web server; it enables the URL rewrite functionality * `index.php` - the application's main entry point * `robots.txt.dist` - a sample robots.txt file that allows/denies bot access to certain areas of your application; activate it by duplicating the file as `robots.txt` and comment out the lines that don't match your environment @@ -69,6 +87,8 @@ These are the modules included by default: * `App` - Core functionality, from rendering, to error reporting * `Page` - Contains functionality for displaying a page +`src/App/assets` holds the front-end sources — `js`, `scss`, `fonts` and `images` — that Vite compiles and copies into the `public` folder. + ### Module contents Each Module folder, in turn, should contain the following folders, unless they are empty: @@ -88,3 +108,8 @@ This directory contains the template files. > `Twig` is used as templating engine. > All template files have the extension `.html.twig`. + +## `test` folder + +This folder contains the application's test suite. +`test/Unit` holds the unit tests, which run with `composer test`.