Update doc

userfrosting · Mar 23, 2024 · 5b52e3c · 5b52e3c
1 parent 06a4ba6
commit 5b52e3c
Show file tree

Hide file tree

Showing 9 changed files with 209 additions and 68 deletions.
diff --git a/pages/01.quick-start/docs.md b/pages/01.quick-start/docs.md
@@ -37,7 +37,10 @@ If any dependencies are not met, an error will occur. Simply try again after fix
 At this point you can run locally using the PHP Server : 
 
 ```bash
-php -S localhost:8080 -t public
+cd UserFrosting
+```
+```bash
+php bakery serve
 ```
 
 You can now access UserFrosting at : [http://localhost:8080](http://localhost:8080)

diff --git a/pages/04.installation/02.environment/01.native/02.install/docs.md b/pages/04.installation/02.environment/01.native/02.install/docs.md
@@ -49,7 +49,7 @@ If the database connection is successful, the installer will then check that the
 At this point you can run locally using the PHP Built-in server : 
 
 ```bash
-php -S localhost:8080 -t public
+php bakery serve
 ```
 
 You can now access UserFrosting at [http://localhost:8080](http://localhost:8080). You should see the default UserFrosting pages and login with the newly created master account. 

diff --git a/pages/09.configuration/02.config-files/docs.md b/pages/09.configuration/02.config-files/docs.md
@@ -114,3 +114,9 @@ Any configuration values under the `site` subarray are automatically passed to T
 ```twig
 <a href="https://twitter.com/{{site.twitter}}">Follow me on Twitter!</a>
 ```
+
+Alternatively, the [config function](/templating-with-twig/filters-and-functions#config) can be used to access any configuration values:
+
+```twig
+<a href="https://twitter.com/{{ config('site.twitter') }}">Follow me on Twitter!</a>
+```
diff --git a/pages/11.cli/01.commands/docs.md b/pages/11.cli/01.commands/docs.md
@@ -141,15 +141,16 @@ $ php bakery debug -v
 
 The debug command is in fact an aggregator of sub-commands, similar to `bake`. It include the following command by default:
 
-| Command       | Description                                                                    |
-| ------------- | ------------------------------------------------------------------------------ |
-| debug:config  | Test the UserFrosting database config                                          |
-| debug:db      | Test the UserFrosting database connection                                      |
-| debug:events  | List all currently registered events listener for each events.                 |
-| debug:locator | List all locations and streams, with their respective path, to help debugging. |
-| debug:mail    | Display Mail Configuration                                                     |
-| debug:version | Test the UserFrosting version dependencies                                     |
-| sprinkle:list | List all available sprinkles and their params                                  |
+| Command       | Description                                                                    | Require verbose |
+|---------------|--------------------------------------------------------------------------------|:---------------:|
+| debug:config  | Test the UserFrosting database config                                          |                 |
+| debug:db      | Test the UserFrosting database connection                                      |                 |
+| debug:events  | List all currently registered events listener for each events.                 | ✓               |
+| debug:locator | List all locations and streams, with their respective path, to help debugging. | ✓               |
+| debug:mail    | Display Mail Configuration                                                     | ✓               |
+| debug:twig    | List all twig namespaces to help debugging                                     | ✓               |
+| debug:version | Test the UserFrosting version dependencies                                     |                 |
+| sprinkle:list | List all available sprinkles and their params                                  |                 |
 
 Some will be only displayed when the verbose mode is active.
 
@@ -518,6 +519,21 @@ Example result:
 ```
 
 
+### serve
+
+The `serve` command is used to execute [PHP Built-in web server](https://www.php.net/manual/en/features.commandline.webserver.php). This is a simple way to test your application without having to configure a full web server.
+
+```bash
+$ php bakery serve [options]
+```
+
+Hit `ctrl+c` to quit.
+
+| Option                            | Description                                             |
+| --------------------------------- | ------------------------------------------------------- |
+| -p, --port=PORT                   | The port to serve the application on [default: "8080"]. |
+
+
 ### test
 
 The `test` command is used to execute [PHPUnit](https://phpunit.de/) tests.

diff --git a/pages/12.templating-with-twig/03.filters-and-functions/docs.md b/pages/12.templating-with-twig/03.filters-and-functions/docs.md
@@ -6,6 +6,16 @@ taxonomy:
     category: docs
 ---
 
+### config
+
+You can access any [configuration value](/configuration/config-files) directly in your Twig templates using the `config` helper function. For example, to display `site.title`:
+
+```twig
+{{ config('site.title') }}
+```
+
+[notice=warning]Use this carefully, as sensitive information (ie. passwords) could be stored in config ![/notice]
+
 ### checkAccess
 
 You can perform permission checks in your Twig templates using the `checkAccess` helper function. This is useful when you want to render a portion of a page's content conditioned on whether or not a user has a certain permission. For example, this can be used to hide a navigation menu item for pages that the current user does not have access to:

diff --git a/pages/22.upgrading/02.50-to-51/01.changelog/docs.md b/pages/22.upgrading/02.50-to-51/01.changelog/docs.md
@@ -0,0 +1,109 @@
+---
+title: What's new in 5.1
+metadata:
+    description: A detailed look at what's new in UserFrosting 5.1
+taxonomy:
+    category: docs
+---
+
+UserFrosting 5.1 focuses on adding PHP 8.3 support, removing PHP 8.1 support, upgrading Laravel, PHPUnit & FontAwesome dependencies and continue improving code quality.
+
+## Changed Requirements
+UserFrosting 5.1 removes support for PHP version 8.1, which has reached [End Of Life](http://php.net/supported-versions.php) as of November 2023 and won't receive security update as of November 2024. **PHP version 8.3 is now recommended**.
+
+## Upgraded Dependencies
+ - Update from Laravel 8 to Laravel 10
+ - Update from PHPUnit 9 to PHPUnit 10
+ - Update from Monolog 2 to Monolog 3
+ - Update FontAwesome 5 to FontAwesome 6
+
+## Detailed changes
+Changes generally applied across UserFrosting includes : 
+ - Add automated testing against MariaDB [#1238](https://github.com/userfrosting/UserFrosting/issues/1238) on each sprinkles
+ - Complete 100% test coverage & PHPStan Level 8 validation across all default packages
+
+### UserFrosting Framework
+#### General
+- Removed `src/Assets` (it isn't used as part of UserFrosting 5.0) 
+- SprinkleManager is a bit more strict on argument types. Recipe classed must be a `class-string`. The actual instance of the class will now be rejected (it wasn't a documented feature anyway).
+
+#### Fortress
+Complete refactoring of Fortress. Mostly enforcing strict types, updating PHPDocs, simplifying code logic and making uses of new PHP features and method. Most classes have been deprecated and replaced by new classes with updated implementation. 
+
+In general, instead of passing the *schema* in the constructor of Adapters, Transformers and Validators class, you pass it directly to theses class methods. This makes it easier to inject the classes as services and reuse the same instance with different schemas. 
+
+[Check out the updated documentation](/routes-and-controllers/client-input/validation) for more information on new class usage, as well as the upgrade guide. 
+
+#### Config
+- Methods `getBool`, `getString`, `getInt` & `getArray` now return `null` if key doesn't exist, to make it on par with parent `get` method.
+
+#### Alert
+- Messages are now translated at read time ([#1156](https://github.com/userfrosting/UserFrosting/pull/1156), [#811](https://github.com/userfrosting/UserFrosting/issues/811)). Messages will be translated when using `messages` and `getAndClearMessages`. `addMessage` now accept the optional placeholders, which will be stored with the alert message. `addMessageTranslated` is **deprecated**. 
+- Translator is not optional anymore. `setTranslator` method has been removed.
+- `addValidationErrors` is deprecated (N.B.: It can't accept the new `\UserFrosting\Fortress\Validator\ServerSideValidatorInterface`)
+
+#### UniformResourceLocator
+- Two locations cannot have the same name anymore. An `InvalidArgumentException` will be thrown otherwise. (Ref [userfrosting/UserFrosting#1243](https://github.com/userfrosting/UserFrosting/issues/1243)).
+- [*DEPRECATION*] Location's `getSlug` is deprecated (redundant with the name and not really used).
+
+### Core sprinkle
+#### Rework of the assets building commands
+This change allows new bakery command to update Npm assets, and eventually allows sprinkles to replace webpack with something else (eg. Vite). The new commands are :
+  - `assets:install` : Alias for `npm install`.
+  - `assets:update` : Alias for `npm update`.
+  - `assets:webpack` : Alias for `npm run dev`, `npm run build` and `npm run watch`, each used to run Webpack Encore.
+  - `assets:build` : Aggregator command for building assets. Include by default `assets:install` and `assets:webpack`. The `webpack` and `build-assets` command are now alias of this command. `bake` also uses this command now. Sub commands can be added to `assets:build` by listening to `AssetsBuildCommandEvent`.
+
+*tl;dr* : Use `php bakery assets:build` instead of `php bakery webpack` or `php bakery build-assets`. 
+
+See [Assets Chapter](/asset-management) and [Bakery commands](/cli/commands) for more details.
+
+#### Loggers changes
+The different loggers now implement their own interface, for more flexibility with dependency injection. Debuggers should now be injected using their interface, instead of their class name.
+
+| Class name         | Interface                   |
+|--------------------|-----------------------------|
+| DebugLogger        | DebugLoggerInterface        |
+| ErrorLogger        | ErrorLoggerInterface        |
+| MailLogger         | MailLoggerInterface         |
+| QueryLogger        | QueryLoggerInterface        |
+| UserActivityLogger | UserActivityLoggerInterface |
+
+Behind the scene, each interface extends `Psr\Log\LoggerInterface`. Plus, instead of *extending* `Monolog\Logger`, each loggers now *wraps* `Monolog\Logger`. This makes the loggers decoupled from Monolog implementation, in favor of the PSR implementation, making it easier to replace Monolog if required.
+
+Finally, `UserActivityLogger` used to define some constants. These have been moved to `UserActivityTypes` enum.
+
+#### New bakery commands
+- [`serve`](/cli/commands#serve) : Run the php built-in web server to test your application 
+- [`debug:twig`](cli/commands#debug) : List all twig namespaces to help debugging
+
+#### New Twig Function
+Any configuration values can now be accessed in Twig using the [config](templating-with-twig/filters-and-functions#config) helper function. Before, only `site` subarray were available in Twig. Use this carefully, as sensitive information (ie. passwords) could be stored in config !
+
+#### Misc changes
+- Session database model now implements 
+- `UserFrosting\Sprinkle\Core\Database\Models\Interfaces\SessionModelInterface`;
+- Use our own RouterParser, wrapped around Slim's RouteParser. Allows to add 'fallback' routes when names routes are not found.
+
+### Account sprinkle
+Missing permissions slugs were missing from the original seed, and thus from to the database ([#1225](https://github.com/userfrosting/UserFrosting/issues/1225)). See the next page for more information on this.
+
+### Admin Sprinkle
+No significant changes.
+
+### AdminLTE theme
+- Add fallback routes when 'index' is not defined (Fix [#1244](https://github.com/userfrosting/UserFrosting/issues/1244))
+
+## Complete change Log
+
+See the changelog of each component for the complete list of changes included in this release.
+- [Skeleton](https://github.com/userfrosting/UserFrosting/blob/5.1/CHANGELOG.md#510)
+- [Framework](https://github.com/userfrosting/framework/blob/5.1/CHANGELOG.md#510)
+- [Core sprinkle](https://github.com/userfrosting/sprinkle-core/blob/5.1/CHANGELOG.md#510)
+- [Account sprinkle](https://github.com/userfrosting/sprinkle-account/blob/5.1/CHANGELOG.md#510)
+- [Admin sprinkle](https://github.com/userfrosting/sprinkle-admin/blob/5.1/CHANGELOG.md#510)
+- [AdminLTE sprinkle](https://github.com/userfrosting/theme-adminlte/blob/5.1/CHANGELOG.md#510)
+
+## Migrating
+
+Now that we've cover the basics changes, follow on to the next pages to the steps required to bring your app up to date with UserFrosting 5.1.
diff --git a/pages/22.upgrading/02.50-to-51/docs.md → ...22.upgrading/02.50-to-51/02.guide/docs.md b/pages/22.upgrading/02.50-to-51/docs.md → ...22.upgrading/02.50-to-51/02.guide/docs.md
@@ -1,52 +1,12 @@
 ---
-title: 5.0.x to 5.1.x
+title: Upgrade Guide
 metadata:
     description: Upgrade guide from version 5.0.x to 5.1.x
 taxonomy:
     category: docs
 ---
 
-## Overview
-
-UserFrosting 5.1 focuses on adding PHP 8.3 support, removing PHP 8.1 support, upgrading Laravel & PHPUnit dependencies and continue improving code quality.
-
-### Changed PHP Requirements
-UserFrosting 5.1 add official support for PHP 8.3 and remove support for PHP version 8.1. PHP 8.1 has reached [End Of Life](http://php.net/supported-versions.php) as of [insert date here]. **PHP version 8.3 is now recommended**.
-
-### Upgraded Dependencies
- - Update from Laravel 8 to Laravel 10
- - Update from PHPUnit 9 to PHPUnit 10
- - Update from Monolog 2 to Monolog 3
-
-### General
- - Test against MariaDB [#1238](https://github.com/userfrosting/UserFrosting/issues/1238)
-
-### Framework
-- [General] Removed `src/Assets` (it wasn't used as part of UserFrosting 5) 
-- [General] SprinkleManager is a bit more strict on argument types. Recipe classed must be a `class-string`. The actual instance of the class will now be rejected (it wasn't a documented feature anyway).
-- [Fortress] Complete refactoring of Fortress. Mostly enforcing strict types, updating PHPDocs, simplifying code logic and making uses of new PHP features and method. Most classes have been deprecated and replaced by new classes with updated implementation. In general, instead of passing the *schema* in the constructor of Adapters, Transformers and Validators class, you pass it directly to theses class methods. This makes it easier to inject the classes as services and reuse the same instance with different schemas. Checkout the documentation for more information on new class usage. 
-- [Config] Methods `getBool`, `getString`, `getInt` & `getArray` now return `null` if key doesn't exist, to make it on par with parent `get` method.
-- [Alert] Messages are now translated at read time ([#1156](https://github.com/userfrosting/UserFrosting/pull/1156), [#811](https://github.com/userfrosting/UserFrosting/issues/811)). Messages will be translated when using `messages` and `getAndClearMessages`. `addMessage` now accept the optional placeholders, which will be stored with the alert message. `addMessageTranslated` is **deprecated**. 
-- [Alert] Translator is not optional anymore. `setTranslator` method has been removed.
-- [Alert] `addValidationErrors` is deprecated (N.B.: It can't accept the new `\UserFrosting\Fortress\Validator\ServerSideValidatorInterface`)
-
-### Core sprinkle
-- Rework assets building command. This change allows new bakery command to update Npm assets, and eventually allows sprinkles to replace webpack with something else (eg. Vite). The new commands are :
-  - `assets:install` : Alias for `npm install`.
-  - `assets:update` : Alias for `npm update`.
-  - `assets:webpack` : Alias for `npm run dev`, `npm run build` and `npm run watch`, each used to run Webpack Encore.
-  - `assets:build` : Aggregator command for building assets. Include by default `assets:install` and `assets:webpack`. The `webpack` and `build-assets` command are now alias of this command. `bake` also uses this command now. Sub commands can be added to `assets:build` by listening to `AssetsBuildCommandEvent`.
-
-***tl;dr*** Use `php bakery assets:build` instead of `php bakery webpack` or `php bakery build-assets`.
-
-See [Assets Chapter](/asset-management) and [Bakery commands](/cli/commands) for more details.
-
-### Account sprinkle
-- Add missing permissions slugs to the database ([#1225](https://github.com/userfrosting/UserFrosting/issues/1225))
-
-## Upgrading to 5.1.x
-
-Upgrading UserFrosting to `5.1.x` is as simple as updating your `composer.json` file and fetching updated dependencies! First, you'll need to edit your `composer.json`.
+Upgrading UserFrosting to `5.1.x` from `5.0.x` is as simple as updating your `composer.json` file and fetching updated dependencies! First, you'll need to edit your `composer.json`.
 
 Update from : 
 ```json
@@ -69,11 +29,11 @@ To:
 "require": {
     "php": "^8.1",
     "ext-gd": "*",
-    "userfrosting/framework": "^5.1",
-    "userfrosting/sprinkle-core": "^5.1",
-    "userfrosting/sprinkle-account": "^5.1",
-    "userfrosting/sprinkle-admin": "^5.1",
-    "userfrosting/theme-adminlte": "^5.1"
+    "userfrosting/framework": "~5.1.0",
+    "userfrosting/sprinkle-core": "~5.1.0",
+    "userfrosting/sprinkle-account": "~5.1.0",
+    "userfrosting/sprinkle-admin": "~5.1.0",
+    "userfrosting/theme-adminlte": "~5.1.0"
 },
 // ...
 ```
@@ -116,6 +76,8 @@ When calling [`urlFor`](/templating-with-twig/filters-and-functions#urlfor) **in
 
 #### Fortress
 
+addValidationErrors
+
 - `UserFrosting\Fortress\RequestSchema` constructor first argument now accept the schema data as an array, as well as a string representing a path to the schema json or yaml file. The argument can still be omitted to create an empty schema. This change makes `UserFrosting\Fortress\RequestSchema\RequestSchemaRepository` obsolete and and such been ***deprecated***. For example:
   ```php
   // Before
@@ -190,13 +152,3 @@ When calling [`urlFor`](/templating-with-twig/filters-and-functions#urlfor) **in
 - `FormValidationHtml5Adapter` Will now throw an exception on missing field param, instead of returning null.
 
 - In `FormValidationHtml5Adapter`, when using `identical` rule, the validation used to be applied to the "confirmation" field. It will now be applied to the source field, making it consistent with array|json format. For example, if `password` requires to be identical to `passwordc`, the validation was added to the `passwordc` field. Now it's applied to `password`.
-
-## Complete change Log
-
-See the changelog of each component for the complete list of changes included in this release.
-- [Skeleton](https://github.com/userfrosting/UserFrosting/blob/5.1/CHANGELOG.md#510)
-- [Framework](https://github.com/userfrosting/framework/blob/5.1/CHANGELOG.md#510)
-- [Core sprinkle](https://github.com/userfrosting/sprinkle-core/blob/5.1/CHANGELOG.md#510)
-- [Account sprinkle](https://github.com/userfrosting/sprinkle-account/blob/5.1/CHANGELOG.md#510)
-- [Admin sprinkle](https://github.com/userfrosting/sprinkle-admin/blob/5.1/CHANGELOG.md#510)
-- [AdminLTE sprinkle](https://github.com/userfrosting/theme-adminlte/blob/5.1/CHANGELOG.md#510)
diff --git a/pages/22.upgrading/02.50-to-51/03.roadmap/docs.md b/pages/22.upgrading/02.50-to-51/03.roadmap/docs.md
@@ -0,0 +1,30 @@
+---
+title: Coming up next
+metadata:
+    description: 
+taxonomy:
+    category: docs
+---
+
+### UserFrosting 5.2
+
+The main focus of UserFrosting 5.2 will be :
+
+- Replace webpack commonJS definition with ESM
+- Update locales (translations), move them to their custom sprinkle
+- Improve Docker support
+- Add Redis/Memecache session driver
+- (Maybe) Update Laravel to version 11
+- (Maybe) Require PHP 8.2 minimum
+- Etc.
+
+No release date has been determined right now. If you would like to give a hand, don't hesitate to contribute by sending a Pull Request on GitHub, or getting in touch on the [Chat](https://chat.userfrosting.com).
+
+### UserFrosting 6
+
+Meanwhile, work for [UserFrosting 6](/upgrading/46-to-50/roadmap#userfrosting-6) is moving along! As a reminder, UF6 goal is to completely rewrite the frontend, with a brand new custom theme replacing AdminLTE and based on [UIKit](https://getuikit.com). Handlebar and every frontend javascript code will also be replaced with [Vue.js](https://vuejs.org). 
+
+You can find a proof of concept of this new Vue.js based UI (built with UF5) and the foundation of the new theme, **Pink Cupcake**, at the links below.
+
+- [userfrosting/demo-vue](https://github.com/userfrosting/demo-vue/tree/main)
+- [userfrosting/theme-pinkcupcake](https://github.com/userfrosting/theme-pinkcupcake)