diff --git a/pages/07.dependency-injection/04.adding-services/docs.md b/pages/07.dependency-injection/04.adding-services/docs.md index 01f79fa5..ccc7c1b7 100644 --- a/pages/07.dependency-injection/04.adding-services/docs.md +++ b/pages/07.dependency-injection/04.adding-services/docs.md @@ -62,6 +62,21 @@ class MapBuilderService implements ServicesProviderInterface [notice=tip]You'll notice that we've added `use UserFrosting\Sprinkle\Site\GoogleMaps\MapBuilder;` to the top of the file. This means that we don't have to use the fully qualified class name (with the entire namespace) every time we want to refer to the `MapBuilder` class.[/notice] +If you need to pull in another service, for example the config to retrieve an API key, you can add them as the parameter, and the dependency injector will automatically pick it up. + +```php +... +MapBuilder::class => function (Config $config) { + $apiKey = $config['api.key']; + + // Now, actually build the object + $mapBuilder = new MapBuilder($apiKey); + + return $mapBuilder; +}, +... +``` + ### Register your service The next step is to tell UserFrosting to load your service in your [Sprinkle Recipe](/sprinkles/recipe#getservices). To do so, you only need to list all the service providers you want to automatically register inside the `$getServices` property of your sprinkle class : diff --git a/pages/08.routes-and-controllers/04.controller-classes/docs.md b/pages/08.routes-and-controllers/04.controller-classes/docs.md index 60f38b7e..87687d44 100644 --- a/pages/08.routes-and-controllers/04.controller-classes/docs.md +++ b/pages/08.routes-and-controllers/04.controller-classes/docs.md @@ -22,6 +22,9 @@ namespace UserFrosting\Sprinkle\Site\Controller; use UserFrosting\Sprinkle\Site\Model\Owl; +use Psr\Http\Message\ResponseInterface as Response; +use Psr\Http\Message\ServerRequestInterface as Request; + class OwlController { public function getOwls(string $genus, Request $request, Response $response): Response @@ -74,6 +77,9 @@ namespace UserFrosting\Sprinkle\Site\Controller; use UserFrosting\Sprinkle\Site\Model\Owl; use UserFrosting\Sprinkle\Site\Finder\VoleFinder; +use Psr\Http\Message\ResponseInterface as Response; +use Psr\Http\Message\ServerRequestInterface as Request; + class OwlController { public function getOwls(string $genus, Request $request, Response $response, VoleFinder $voleFinder): Response @@ -97,6 +103,9 @@ namespace UserFrosting\Sprinkle\Site\Controller; use UserFrosting\Sprinkle\Site\Model\Owl; use UserFrosting\Sprinkle\Site\Finder\VoleFinder; +use Psr\Http\Message\ResponseInterface as Response; +use Psr\Http\Message\ServerRequestInterface as Request; + class OwlController { /** @@ -148,6 +157,9 @@ namespace UserFrosting\Sprinkle\Site\Controller; use UserFrosting\Sprinkle\Site\Model\Owl; use UserFrosting\Sprinkle\Site\Finder\VoleFinder; +use Psr\Http\Message\ResponseInterface as Response; +use Psr\Http\Message\ServerRequestInterface as Request; + class GetOwlsAction { public function __invoke(string $genus, Request $request, Response $response, VoleFinder $voleFinder): Response diff --git a/pages/14.database/04.seeding/docs.md b/pages/14.database/04.seeding/docs.md index 2cc7e2e3..aef2cc8d 100644 --- a/pages/14.database/04.seeding/docs.md +++ b/pages/14.database/04.seeding/docs.md @@ -42,7 +42,7 @@ class MySeed implements SeedInterface ## Registering Seeds -To be picked up by the `seed` bakery command, a seed class files must first be registered in the the *Sprinkle Recipe*, using the `SeedRecipe` sub-recipe and the `getSeeds():array` method: +To be picked up by the `seed` bakery command, a seed class files must first be registered in the *Sprinkle Recipe*, using the `SeedRecipe` sub-recipe and the `getSeeds():array` method: ```php Dependency Injection -Services have been updated for UserFrosting 5. While the principle is the same, the way to register service is different. Services are now served by the new dependency injection container, PHP-DI. You should head over to the [Dependency Injection Chapter](/dependency-injection) to learn more about PHP-DI integration in UserFrosting 5 before going further. +Services have been updated for UserFrosting 5. While the principle is the same, the way to register a service is different. Services are now served by the new dependency injection container, PHP-DI. You should head over to the [Dependency Injection Chapter](/dependency-injection) to learn more about PHP-DI integration in UserFrosting 5 before going further. Your services definition must first be updated to implement `UserFrosting\ServicesProvider\ServicesProviderInterface`. For example: @@ -167,7 +167,7 @@ class ServicesProvider implements ServicesProviderInterface You'll also need to **register your service** in your recipe. Checkout [Adding Services](/dependency-injection/adding-services) for more information. -Finally, instead or injecting the whole container and retrieving your service from it, your should inject the service directly into the class using [autowiring](/dependency-injection/the-di-container#autowiring) in the class constructor or thought [route service injection](/routes-and-controllers/controller-classes#service-injection) for example. +Finally, instead of injecting the whole container and retrieving your service from it, you should inject the service directly into the class using [autowiring](/dependency-injection/the-di-container#autowiring) in the class constructor or thought [route service injection](/routes-and-controllers/controller-classes#service-injection) for example. For example: @@ -193,15 +193,21 @@ The classmapper has been removed in UF5. PHP-DI should be used instead, via the ### Migrations -Migration are mostly the same, only the class structure as changed, as well as the need to register migration in your Sprinkle Recipe. The key points regarding migration are as follow : +Migrations are mostly the same, only the class structure as changed, as well as the need to register migration in your Sprinkle Recipe. The key points regarding migration are as follow: -1. Up/Down return type : The `up()` and `down()` method [must now return `void`](/database/migrations#base-class) +1. Up/Down return type : The `up()` and `down()` method [must now have a return type of `void`](/database/migrations#base-class) -2. Migration must [now implement](/database/migrations#base-class) `UserFrosting\Sprinkle\Core\Database\Migration`. Change `use UserFrosting\System\Bakery\Migration;` to `use UserFrosting\Sprinkle\Core\Database\Migration;` in every one of your migrations. +2. Migrations must [now extend](/database/migrations#base-class) `UserFrosting\Sprinkle\Core\Database\Migration`. Change `use UserFrosting\System\Bakery\Migration;` to `use UserFrosting\Sprinkle\Core\Database\Migration;` in every one of your migrations. 3. [Dependencies](/database/migrations#dependencies) must now be declared in a static property. Change `public $dependencies = [];` to `public static $dependencies = [];` in every one of your migrations. -4. Migration are not auto-discovered anymore. You need to add them to your sprinkle recipe, using `MigrationRecipe`. See [the migration chapter](/database/migrations#sprinkle-recipe) for more information and a detailed guide. +4. Migrations are not auto-discovered anymore. You need to add them to your sprinkle recipe, using `MigrationRecipe`. See [the migration chapter](/database/migrations#sprinkle-recipe) for more information and a detailed guide. + +### Seeds + +Seeds are also mostly the same, they just need to implement `\UserFrosting\Sprinkle\Core\Seeder\SeedInterface`, and have a `run()` function with a return type of `void`. They are also not auto-discovered, so need to be added to your sprinkle recipe using `SeedRecipe`. + +See [the seeding chapter](/database/seeding) for more details. ### Models @@ -209,16 +215,16 @@ The only change in database model is the `$timestamps` property is not `true` by ### Routes -The way to register route as changed. The definition is mostly the same, however the routes are now a real PHP classes, instead of static php resources. Check out the [Registering routes](/routes-and-controllers/registering-routes) guide for more information. +The way to register routes has changed. The definition is mostly the same, however the routes are now real PHP classes, instead of static php resources. Check out the [Registering routes](/routes-and-controllers/registering-routes) guide for more information. -To updated your routes, you should start by : +To updated your routes, you should start by: 1. Move your routes from `app/routes/*` to `app/src/Routes/*`; 2. Update your routes definitions so it's a class [implementing RouteDefinitionInterface](/routes-and-controllers/registering-routes) 3. Register your routes in your Sprinkle Recipe. -A few other key point to know: -1. Route groups definition has changed. See [Slim Documentation](https://www.slimframework.com/docs/v4/objects/routing.html#route-groups) for more information +A few other key points to know: +1. Definitions for route groups has changed. See [Slim Documentation](https://www.slimframework.com/docs/v4/objects/routing.html#route-groups) for more information 2. Controller resolution should be updated to make use of [PHP’s `::class` operator](https://www.slimframework.com/docs/v4/objects/routing.html#container-resolution) 3. Middleware must now be called by their class name. For example, `authGuard` must be updated to `UserFrosting\Sprinkle\Account\Authenticate\AuthGuard::class` @@ -260,21 +266,21 @@ This also mean the **Classmapper** is not available anymore in sprunjes. You sho ### Controllers -Simple changes have been made to controller classes : +Simple changes have been made to controller classes: 1. Remove `extends SimpleController`, no extension is required anymore. 2. `use Slim\Http\Request;` must be changed to `use Psr\Http\Message\ServerRequestInterface as Request;` 3. `use Slim\Http\Response;` must be changed to `use Psr\Http\Message\ResponseInterface as Response;` -4. Since the DI container is not available globally in controllers, the services you requires must be [injected in constructor](/routes-and-controllers/controller-classes#service-injection) +4. Since the DI container is not available globally in the controllers, the services you require must be [injected via the constructor](/routes-and-controllers/controller-classes#service-injection) 1. For example, to use the `view` service, inject `Slim\Views\Twig;` See [Controller classes](/routes-and-controllers/controller-classes) guide for more information. -[note]If your sprinkle extends a controller class from a default sprinkle instead of `SimpleController`, note that **every** controller classes from default sprinkles have been moved, renamed and rewritten as *Action classes*. Make sure to check out the sprinkle source code to find out how to update your sprinkle.[/note] +[note]If your sprinkle extends a controller class from a default sprinkle instead of `SimpleController`, note that **every** controller class from the default sprinkles have been moved, renamed and rewritten as *Action classes*. You will need to check out the sprinkle source code to find out how to update your sprinkle.[/note] ### Bakery -Simple changes have been made to bakery commands : +Simple changes have been made to bakery commands: 1. Command must extend `Symfony\Component\Console\Command\Command` instead of `UserFrosting\System\Bakery\BaseCommand` 2. Service should be injected through the class constructor (don't forget to call the parent constructor) or via [attribute injection](https://php-di.org/doc/attributes.html#inject). @@ -287,7 +293,7 @@ Also note that the `create-admin` command has been renamed `create:admin-user`. ### Resources Stream / Locator -Not must as changed regarding the Resource Locator. Refer to the [Locator Service](/advanced/locator) page for more information. Note however that the two stream below have been renamed: +Not must has changed regarding the Resource Locator. Refer to the [Locator Service](/advanced/locator) page for more information. Note however that the two streams below have been renamed: 1. log -> logs 2. session -> sessions diff --git a/pages/22.upgrading/02.50-to-51/02.guide/docs.md b/pages/22.upgrading/02.50-to-51/02.guide/docs.md index 05797b18..08dde2e7 100644 --- a/pages/22.upgrading/02.50-to-51/02.guide/docs.md +++ b/pages/22.upgrading/02.50-to-51/02.guide/docs.md @@ -81,13 +81,13 @@ $ php bakery bake ### Font Awesome -UserFrosting 5.1 now ship with Font Awesome 6 in the AdminLTE theme. While Font Awesome 6 is backward compatible with Font Awesome 5, some icons [have been renamed](https://docs.fontawesome.com/web/setup/upgrade/whats-changed#icons-renamed-in-version-6) and you might need to manually update these in your sprinkle. +UserFrosting 5.1 now ships with Font Awesome 6 in the AdminLTE theme. While Font Awesome 6 is backward compatible with Font Awesome 5, some icons [have been renamed](https://docs.fontawesome.com/web/setup/upgrade/whats-changed#icons-renamed-in-version-6) and you might need to manually update these in your sprinkle. -Checkout Font Awesome guide for more information : [https://docs.fontawesome.com/web/setup/upgrade/whats-changed](https://docs.fontawesome.com/web/setup/upgrade/whats-changed) +Checkout the Font Awesome guide for more information : [https://docs.fontawesome.com/web/setup/upgrade/whats-changed](https://docs.fontawesome.com/web/setup/upgrade/whats-changed) ### Missing default permissions -Some build-in permissions [were missing from the database](https://github.com/userfrosting/UserFrosting/issues/1225) : +Some built-in permissions [were missing from the database](https://github.com/userfrosting/UserFrosting/issues/1225) : - `uri_role` - `uri_roles` - `uri_permissions` @@ -100,28 +100,28 @@ Some build-in permissions [were missing from the database](https://github.com/us - `view_system_info` - `clear_cache` -To add them to the database, run `php bakery seed` and select `UserFrosting\Sprinkle\Account\Database\Seeds\DefaultPermissions`. Theses will also be added to the `site-admin` role when running the seed. +To add them to the database, run `php bakery seed` and select `UserFrosting\Sprinkle\Account\Database\Seeds\DefaultPermissions`. These will also be added to the `site-admin` role when running the seed. -[notice=warning]If your application defines custom permissions to the `site-admin` role or you customized this role, **do not run the seed** unless you want to lose any custom changes. Running the seed will revert back that role to it's default state.[/notice] +[notice=warning]If your application defines custom permissions to the `site-admin` role or you customized this role, **do not run the seed** unless you want to lose any custom changes. Running the seed will revert back the role to it's default state.[/notice] The `site-admin` role is now on par with the root user permission by default, except for the last two permissions added, `view_system_info` & `clear_cache`. Theses can be added to the role if desired using the UI. ### `urlFor` service change -When calling [`urlFor`](/templating-with-twig/filters-and-functions#urlfor) **in PHP** (not Twig) to generate a route from it's name, the service as been replaced. Find and replace the following import to upgrade: +When calling [`urlFor`](/templating-with-twig/filters-and-functions#urlfor) **in PHP** (not Twig) to generate a route from its name, the service has been replaced. Find and replace the following import to upgrade: - Find : `use Slim\Interfaces\RouteParserInterface;` - Replace : `use UserFrosting\Sprinkle\Core\Util\RouteParserInterface;` ### Alerts -When using the [alerts](/advanced/alert-stream) service, replace `addMessageTranslated(...);` with `addMessage(...);`. The old method is still available, but deprecated and will be removed in a future version. +When using the [alerts](/advanced/alert-stream) service, replace `addMessageTranslated(...);` with `addMessage(...);`. The old method is still available, but it is deprecated and will be removed in a future version. ### Fortress -Fortress has been complexly rewritten for UserFrosting 5.1. Most class have been kept and will continue working, but these have been marked deprecated and will be removed in future version. It is recommended to upgrade your code now to avoid issues later. +Fortress has been completely rewritten for UserFrosting 5.1. Most classes have been kept and will continue working, but these have been marked deprecated and will be removed in future version. It is recommended to upgrade your code now to avoid issues later. #### RequestSchema -`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: +The `UserFrosting\Fortress\RequestSchema` constructor's first argument now accepts 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 @@ -243,6 +243,8 @@ $errors = $this->validator->validate($schema, $data); if (count($errors) !== 0) { $e = new ValidationException(); $e->addErrors($errors); + + throw $e; } ```