Configurable Generation of Web & API Routes

[yourchocomate]

Feature: Configurable Generation of Web & API Routes

Overview

This PR addresses issue #2110 by enabling developers to control whether web and API route files and methods are generated in each module's RouteServiceProvider. In previous versions, methods for web and API routes were always included—even if the corresponding route files were missing—which caused errors.

Problem Statement

Previously, even when developers disabled generation of routes/web.php or routes/api.php (by adjusting configuration), the RouteServiceProvider would still contain the methods mapWebRoutes() and/or mapApiRoutes(). These would reference missing files, causing runtime errors.

Solution Summary

This PR introduces more granular configuration and stub-processing so that:

• You can explicitly enable or disable generation of web and/or API routes via config.
• The stub for RouteServiceProvider will only include code for enabled route types, avoiding references to files that don't exist.
• This is accomplished by adding removal tag markers in the stub and processing them based on configuration.

Breakdown of the Approach

1. Configuration Improvements

• Added new boolean options web and api under modules.paths.generator.routes in the config.
• Developers can now specify exactly which types of routes should be generated.

2. Conditional Code Generation

• RouteProviderMakeCommand checks these configuration settings.
• Only includes mapWebRoutes() and/or mapApiRoutes() methods in the generated file if corresponding flags are true.

3. Stub Template Enhancements

• Special tags (%START_WEB_ROUTES%...%END_WEB_ROUTES% and %START_API_ROUTES%...%END_API_ROUTES%) have been added to the stub template.
• These mark code sections to be conditionally removed or kept during file generation.

4. Enhanced Stub Processing

• The Stub class now:
  • Accepts a list of tags to remove.
  • Strips out marked sections from the stub template as needed.
  • Cleans up any leftover markers, so the result is clean.

---

How Removal Tag Markers Work (Contributor Docs)

What are they?

• Markers in stub templates to wrap code that should only be present under certain conditions.

Syntax:

• Start: %START_TAG_NAME%
• End: %END_TAG_NAME%

When you specify a tag (e.g., WEB_ROUTES) for removal, all code between its start and end markers is removed from the generated file.

Implementation Internals

• The Stub class includes:
  1. $removalTags — array of markers to remove.
  2. setRemovalTags(array $tagsArray) — specify markers to remove.
  3. removeContentsBetweenTagMarkers(string $tag, string $contents) — removes code wrapped in that tag, via regex.
  4. cleanUpTagMarkers(string $contents) — removes any tags left over.

Example Usage

In a stub (route-provider.stub):

%START_WEB_ROUTES%
protected function mapWebRoutes(): void
{
    Route::middleware('web')->group(module_path($this->name, '$WEB_ROUTES_PATH$'));
}
%END_WEB_ROUTES%

In the generation command:

return (new Stub('/route-provider.stub', [
    'WEB_ROUTES_PATH' => $this->getWebRoutesPath(),
    // ... more replacements ...
]))->setRemovalTags([
    !$this->shouldGenerateWebRoutes() ? 'WEB_ROUTES' : null,
    !$this->shouldGenerateApiRoutes() ? 'API_ROUTES' : null,
])->render();

Result:
If 'web' => false in config, the mapWebRoutes() function will not be present in the provider class.

Contributor Benefits

• Reusable: The tagging system can be used in any stub file for future conditional needs.
• Flexible: Multiple or complex combinations of conditional code possible via multiple tags.
• Clean Output: Leftover markers are automatically cleaned up.
• Backward Compatible: Old stubs without tags continue to work.

Technical Details

• Regex uses the s flag (dot matches newlines): /\%START_TAG%.*?\%END_TAG%/s
• Tags must be uppercase and match exactly.
• Null values are filtered from the removal tag array.

---

What Was Changed

• config/config.php: Added 'web' => true, 'api' => true to route generation config block.
• RouteProviderMakeCommand.php:
  • Added methods shouldGenerateWebRoutes() and shouldGenerateApiRoutes().
  • Updated getTemplateContents() to use removal tags logic.
• route-provider.stub: Code wrapped in conditional tag markers.
• Stub.php: Now supports conditional removal of tagged code blocks.

---

Configuration Usage

Easily control which routes are generated in config/modules.php:

'routes' => [
    'path' => 'routes', 
    'generate' => true, 
    'web' => true,    // Change to false to skip web routes
    'api' => false    // Change to false to skip API routes
],

If web or api is set to false, the corresponding method will not be present in the generated provider file, avoiding references to missing route files.

---

Testing Performed

• Confirmed mapWebRoutes() is only generated if web => true.
• Confirmed mapApiRoutes() is only generated if api => true.
• Confirmed both generated if both true.
• Neither generated if both false.
• Default config (true for both) remains fully compatible.

Related Issue

Closes #2110