Skip to content

Commit

Permalink
Merge pull request #1931 from spryker/feature/SDK-2825
Browse files Browse the repository at this point in the history 
SDK-2825: Rework the documentation for evaluator
  • Loading branch information
@AlexSlawinski
AlexSlawinski committed Jun 22, 2023
2 parents f700ab1 + 0e8735d commit 6a542cf
Show file tree
Hide file tree
Showing 8 changed files with 393 additions and 262 deletions.
122 changes: 85 additions & 37 deletions ...-upgradable/upgradability-guidelines/additional-logic-in-dependency-provider.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,73 +4,121 @@ description: Reference information for evaluator tools.
template: howto-guide-template
---

This document explains how you can bypass issues with additional logic inside the dependency provider’s methods.
The *Additional logic in dependency provider* check checks the way plugins are registered in the dependency provider on the project level.

## Problem description

On the project level, developers use `if` constructs with variety of expressions in dependency providers to register the plugins in particular cases only.
At the project level, developers use `if` structures with diverse expressions in dependency providers to selectively register plugins in specific cases.

Not all possible expressions are needed inside of the `if` statements for plugin registration and not all of them are supported. This check verifies that if an `if` construct is used for plugin registration, then only one of the following expressions is used:
The expressions utilized within the `if` statements should not overly complicate the logic within the dependency provider.
This check ensures that if an `if` structure is used for plugin registration, only one of the subsequent expressions is used:

`class_exists` it is allowed for BC reasons
1. `class_exists` function call

```php
class_exists(\Foo\Bar::class) function call
```

`isDevelopment` function calls - it is allowed for plugins that are needed in development mode only (e.g. profiling, debug, etc.)

```php
$this->getConfig()->isDevelopmentConsoleCommandsEnabled() function calls
```
Usage of the `class_exists` function call inside of the `if` statement is allowed for BC reasons only.

## Example of code that causes an upgradability error

The method `getFormPlugins` in `FormDependencyProvider` contains unsupported expressions in the `if` construct `$alwaysAddPlugin`.
Below is an example of the `class_exists` function call inside of the `if` statement:

```php
use Spryker\Yves\Form\FormDependencyProvider as SprykerFormDependencyProvider;
namespace Pyz\Zed\Form;

use Spryker\Zed\WebProfiler\Communication\Plugin\Form\WebProfilerFormPlugin;

class FormDependencyProvider extends SprykerFormDependencyProvider
{
...

/**
* @return array<\Spryker\Shared\FormExtension\Dependency\Plugin\FormPluginInterface>
*/
protected function getFormPlugins(): array
{
$plugins = [
new ValidatorExtensionFormPlugin(),
];

$plugins[] = new CsrfFormPlugin();

$alwaysAddPlugin = true;
$formPlugins = [];

if ($alwaysAddPlugin) {
$plugins[] = new WebProfilerFormPlugin();
if (class_exists(WebProfilerFormPlugin::class)) {
$formPlugins[] = new WebProfilerFormPlugin();
}

return $formPlugins;
}
}
```

2. `isDevelopment` function call

The usage of `isDevelopment` checks is allowed in order to register the plugins that are needed in development mode only (e.g. profiling, debug, etc.).

```php
namespace Pyz\Zed\Console;

use Spryker\Zed\Console\ConsoleDependencyProvider as SprykerConsoleDependencyProvider;
use Spryker\Zed\Development\Communication\Console\CodeTestConsole;
use Spryker\Zed\Kernel\Container;

class ConsoleDependencyProvider extends SprykerConsoleDependencyProvider
{
/**
* @param \Spryker\Zed\Kernel\Container $container
*
* @return array<\Symfony\Component\Console\Command\Command>
*/
protected function getConsoleCommands(Container $container): array
{
$commands = [];

return $plugins;
if ($this->getConfig()->isDevelopmentConsoleCommandsEnabled()) {
$commands[] = new CodeTestConsole();
}

return $commands;
}
}
```

### Related error in the Evaluator output
## Example of an Evaluator error message

```bash
======================
MULTIDIMENSIONAL ARRAY
======================

+---+------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------+
| # | Message | Target |
+---+------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------+
| 1 | The condition statement if ($alwaysAddPlugin) {} is forbidden in the DependencyProvider | /spryker/b2c-demo-shop/src/Pyz/Zed/Checkout/CheckoutDependencyProvider.php |
+---+------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------+
+---+------------------------------------------------------------------------------------+-------------------------------------------------------------------+
| # | Message | Target |
+---+------------------------------------------------------------------------------------+-------------------------------------------------------------------+
| 1 | The condition statement if ($alwaysTrue) {} is forbidden in the DependencyProvider | <path_to_project>/Pyz/Zed/Checkout/CheckoutDependencyProvider.php |
+---+------------------------------------------------------------------------------------+-------------------------------------------------------------------+

```
## Example of code that causes an upgradability error
The method `getFormPlugins` in `FormDependencyProvider` contains unsupported expressions in the `if` construct `$alwaysAddPlugin`.
```php
namespace Pyz\Zed\Form;

use Spryker\Zed\WebProfiler\Communication\Plugin\Form\WebProfilerFormPlugin;

class FormDependencyProvider extends SprykerFormDependencyProvider
{
/**
* @return array<\Spryker\Shared\FormExtension\Dependency\Plugin\FormPluginInterface>
*/
protected function getFormPlugins(): array
{
$formPlugins = [];
$alwaysTrue = true;

if ($alwaysTrue) {
$formPlugins[] = new WebProfilerFormPlugin();
}

return $formPlugins;
}
}
```
### Resolving the error
To resolve the error provided in the example, try the following in the provided order:
1. Try to avoid using conditions in the dependency providers.
To resolve the issue:
1. Try to avoid the usage of conditions in the dependency providers.
2. Use only the supported expressions in the `if` construct.
53 changes: 24 additions & 29 deletions ...ines/keeping-a-project-upgradable/upgradability-guidelines/dead-code-checker.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,45 +8,40 @@ The dead code checker checks for dead code that extends core classes in your pro

## Problem description

The project can extend core classes and after some time it can become unusable due to core changes. As a result, issues related to the project's upgradability arise.
It checks possible dead classes. For obvious reasons, the Spryker kernel classes such as `Factory`, `Facade` or `DependencyProvider` tend to be skipped.
Optionally, you can mute the dead code checker for a specific class with `@evaluator-skip-dead-code`.
The project has the capability to extend Spryker core classes, but over time, it may become ineffective due to changes in the project or core components.
This results in unnecessary additional time investment from developers, as they need to update the dead code.
This check examines potential obsolete classes, with a tendency to overlook important Spryker kernel classes like `Factory`, `Facade`, or `DependencyProvider`.
If desired, you have the option to disable the dead code checker for a particular class using the `@evaluator-skip-dead-code` annotation.

## Example of code that causes an upgradability error:
## Example of an Evaluator error message

The code has a class that doesn't have explicit initialization in project module:
```bash
=================
DEAD CODE CHECKER
=================

+---+---------------------------------------------------------------------------------+--------------------------------------------------+
| # | Message | Target |
+---+---------------------------------------------------------------------------------+--------------------------------------------------+
| 1 | Class "Pyz/Zed/Single/Communication/Plugin/SinglePlugin" is not used in project | Pyz/Zed/Single/Communication/Plugin/SinglePlugin |
+---+---------------------------------------------------------------------------------+--------------------------------------------------+
```

Unused class `Pyz/Zed/Single/Communication/Plugin/SinglePlugin` that produces an error:

```bash
namespace Spryker/Zed/Module;
namespace Pyz\Zed\Single\Communication\Plugin;

use Spryker\Zed\Single\Communication\Plugin\SinglePlugin as SprykerSinglePlugin;

class SinglePlugin extend SprykerSinglePlugin
class SinglePlugin extends SprykerSinglePlugin
{
/**
* @return void
*/
public function run(): void
{
...
}
...
}
```
### Related error in the Evaluator output:

```bash
DEAD CODE CHECKER
=================

+---+----------------------------------------------------------------------+-----------------------------------------------------------------------+
| # | Message | Target |
+---+----------------------------------------------------------------------+-----------------------------------------------------------------------+
| 1 | Class "Spryker/Zed/Module/SinglePlugin" is not used in project | Spryker/Zed/Module/SinglePlugin |
+---+----------------------------------------------------------------------+-----------------------------------------------------------------------+
```
### Resolving the error

### Resolving the error:
To resolve the error provided in the example, try the following in the provided order:
1. Skip the violation with an annotation.
2. Remove the unused class.
To resolve the error:

1. Remove the unused dead code in project.
64 changes: 28 additions & 36 deletions ...g-a-project-upgradable/upgradability-guidelines/minimum-allowed-shop-version.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,54 +4,46 @@ description: Reference information for evaluator tools.
template: howto-guide-template
---

The shop project dependencies should be at least a supported release version. This document explains the problem and how to address it.
The *Minimum allowed shop version* check makes sure that the project uses one of the supported product releases by the [Spryker Code Upgrader](/docs/scu/dev/onboard-to-spryker-code-upgrader/prepare-a-project-for-spryker-code-upgrader.html).

## Problem description

The shop contains old package dependencies that are already unsupported. This can cause issues related to the project's upgradability.

## Example of code that causes an upgradability error

composer.lock contains unsupported package versions
```json
{
"_readme": [
"This file locks the dependencies of your project to a known state",
"Read more about it at https://getcomposer.org/doc/01-basic-usage.md#installing-dependencies",
"This file is @generated automatically"
],
"content-hash": "7f3bcb8eeee91ab717f561b035b8df84",
"packages": [
{
"name": "spryker-feature/agent-assist",
"version": "202203.0",
...
},
{
"name": "spryker/availability-gui",
"version": "6.5.9",
...
}
]
}
To enable smooth upgradability of the project using the [Spryker Code Upgrader](/docs/scu/dev/onboard-to-spryker-code-upgrader/prepare-a-project-for-spryker-code-upgrader.html), it is essential for the project to adhere to the minimum required Spryker product release.

In case the project does not utilize the feature packages, it is necessary to ensure that the corresponding Spryker module versions are used.

## Example of an Evaluator error message

Below is an example of when a used feature package version doesn't correspond to the minimum required version:

```shell
============================
MINIMUM ALLOWED SHOP VERSION
============================

+---+---------------------------------------------------------------------------------------------------------------------------+---------------------------------------+
| # | Message | Target |
+---+---------------------------------------------------------------------------------------------------------------------------+---------------------------------------+
| 1 | The package "spryker-feature/agent-assist" version "202108.0" is not supported. The minimum allowed version is "202204.0" | spryker-feature/agent-assist:202108.0 |
+---+---------------------------------------------------------------------------------------------------------------------------+---------------------------------------+
```

### Related error in the Evaluator output
Below is an example of when the used Spryker package version doesn't correspond to the minimum required version:

```shell
============================
MINIMUM ALLOWED SHOP VERSION
============================

+---+-------------------------------------------------------------------------------------------------------------------+---------------------------------------+
| # | Message | Target |
+---+-------------------------------------------------------------------------------------------------------------------+---------------------------------------+
| 1 | The package "spryker-feature/agent-assist" version "202203.0" is not supported. The minimum allowed version is "202204.0" | spryker-feature/agent-assist:202203.0 |
+---+-------------------------------------------------------------------------------------------------------------------+---------------------------------------+
| 2 | The package "spryker/availability-gui" version "6.5.9" is not supported. The minimum allowed version is "6.6.0" | spryker/availability-gui:6.5.9 |
+---+-------------------------------------------------------------------------------------------------------------------+---------------------------------------+
+---+-----------------------------------------------------------------------------------------------------------------+--------------------------------+
| # | Message | Target |
+---+-----------------------------------------------------------------------------------------------------------------+--------------------------------+
| 1 | The package "spryker/availability-gui" version "6.5.9" is not supported. The minimum allowed version is "6.6.0" | spryker/availability-gui:6.5.9 |
+---+-----------------------------------------------------------------------------------------------------------------+--------------------------------+
```

### Resolving the error

To resolve this issue, update the outdated dependencies to the current release or version.
To resolve this issue:

1. Update the outdated dependencies to make it correspond to the minimum required version.
Loading

0 comments on commit 6a542cf

Please sign in to comment.