Implement addMiddlewarePrependToGroup in AppBootstrapBuilder

[DenTray]

Description

What needs to be done?

Implement a new method addMiddlewarePrependToGroup(string $group, array|string $middleware, InsertPositionEnum $position = InsertPositionEnum::End): self in AppBootstrapBuilder.

This method must update bootstrap/app.php and add the call $middleware->prependToGroup($group, [...]) inside the withMiddleware(...) closure in the Application::configure(...) chain.

Behavior rules:

1. If withMiddleware(...) does not exist in bootstrap/app.php:

   • Create ->withMiddleware(function (Middleware $middleware): void { ... }) inside the Application::configure(...) method chain.
   • Add $middleware->prependToGroup($group, [...]) inside that closure.

2. If withMiddleware(...) exists, but there is no prependToGroup call for the target group:

   • Add a new call to $middleware->prependToGroup($group, [...]) inside the existing closure.

3. If prependToGroup for the target group already exists:

   • Append the passed middleware values to the existing array.
   • Do not add duplicates.
   • If a passed middleware already exists in the array, skip it.

4. If $middleware is passed as a single string:

   • Treat it as an array with one item.

5. If all passed middleware values already exist in the target prependToGroup call:

   • Do not change the file content.

6. If prependToGroup exists for other groups:

   • Do not modify those calls.
   • Add or update only the call for the requested group.

7. If the parsed bootstrap/app.php file contains a class, trait, interface, or enum declaration:

   • Throw InvalidBootstrapAppFileException.

Implementation requirements:

• Automatically add import for Illuminate\Foundation\Configuration\Middleware if it is missing.
• Preserve the original file formatting.

Expected Outcome

What is the expected result?

The project has a working addMiddlewarePrependToGroup method in AppBootstrapBuilder that safely updates bootstrap/app.php.

Result expectations:

• A new visitor AddMiddlewarePrependToGroup extended from AbstractAppBootstrapVisitor is added in src/Visitors/AppBootstrapVisitors/AddMiddlewarePrependToGroup.php.
• AppBootstrapBuilder exposes the new public method.
• The method creates withMiddleware(...) when it is missing.
• The method adds a new prependToGroup call when the target group does not exist.
• The method updates an existing prependToGroup call for the target group without duplicates.
• The method supports both array and string input.
• The method imports Illuminate\Foundation\Configuration\Middleware automatically if needed.
• The method preserves file formatting and does not modify unrelated code.
• Invalid bootstrap file structures cause InvalidBootstrapAppFileException.

Verification Scenarios

How can this be tested?

1. withMiddleware(...) is missing:

   • Run addMiddlewarePrependToGroup('api', [AutoDocMiddleware::class, 'throttle:60,1']).
   • Verify that withMiddleware(function (Middleware $middleware): void { ... }) is created in bootstrap/app.php.
   • Verify that $middleware->prependToGroup('api', [...]) is added inside it.

2. withMiddleware(...) exists, but prependToGroup('api', ...) does not exist:

   • Run the method.
   • Verify that a new prependToGroup('api', [...]) call is added to the end of existing closure.
   • Run the method with the start position arg.
   • Verify that a new prependToGroup('api', [...]) call is added to the start of existing closure.

3. prependToGroup('api', ...) exists and none of the passed middleware are present:

   • Verify that all new middleware are appended to the existing array.

4. prependToGroup('api', ...) exists and some passed middleware are already present:

   • Verify that only missing middleware are added.
   • Verify that duplicates are not created.

5. prependToGroup('api', ...) exists and all passed middleware are already present:

   • Verify that the file remains unchanged.

6. prependToGroup(...) exists for another group, for example web:

   • Run the method for api.
   • Verify that the web group is not changed.
   • Verify that a new api call is added or updated correctly.

7. Pass a single string instead of an array:

   • Run addMiddlewarePrependToGroup('api', 'throttle:60,1').
   • Verify that the result matches behavior for a one-item array.

8. Pass duplicated values in the input array:

   • Example: ['throttle:60,1', 'throttle:60,1']
   • Verify that only one value is added.

9. File contains class, trait, interface, or enum:

   • Verify that the method throws InvalidBootstrapAppFileException.

10. Missing import for Illuminate\Foundation\Configuration\Middleware:

    • Verify that the import is added automatically.

11. Existing import already present:

    • Verify that the import is not duplicated.

12. Formatting:

    • Verify that the original formatting is preserved after save.
13. Add automated tests for all scenarios above.
14. Ensure no debug information or errors in the console.

[AZabolotnikov]

During the review of PR #74, the following cases were identified and agreed to be handled in separate pull requests:

1. Middleware array formatting in the printer — the current implementation does not preserve the original formatting of the middleware array. A follow-up PR will handle proper multiline formatting.
2. Creating the withMiddleware method when it is absent — if withMiddleware(...) does not exist in bootstrap/app.php, the current implementation does not create it. This case will be covered in a separate PR.
3. Namespace specified inline in the array instead of via an import — when the original file uses a fully-qualified class name directly inside the array (e.g. Illuminate\Auth\Middleware\Authenticate::class) rather than a use import, the visitor does not handle this correctly. This will be addressed in a dedicated PR.
4. Middleware deduplication when merging arrays with the same class name but different namespaces — isSameMiddleware() compares the class name as written in the AST, so a fully-qualified name and a short (imported) name for the same class are never considered equal, leading to duplicates. This comparison logic will be fixed in a separate PR.

FYI @DenTray @artengin