Refactor codebase to adhere to strict coding standards

- Split DocumentationService into MarkdownRenderer and ContentProcessor for better separation of concerns
- Apply strict types (strict_types=1) to Controllers and Services
- Optimize routes/web.php by removing closures and utilizing controller groups
- Clean up response handling in DocumentController and LocaleController"

Author: Xoshbin

routes/web.php

@@ -4,58 +4,41 @@
 use Xoshbin\Pertuk\Http\Controllers\DocumentController;
 use Xoshbin\Pertuk\Http\Controllers\LocaleController;
 
-// Locale switching route (global, not prefixed) - supports both GET and POST
+// Locale switching route
 Route::match(['GET', 'POST'], '/locale/{locale}', [LocaleController::class, 'setLocale'])
     ->name('pertuk.locale.set')
     ->where('locale', implode('|', config('pertuk.supported_locales', ['en'])));
 
-$routePrefix = config('pertuk.route_prefix', 'docs');
-$middleware = config('pertuk.middleware', []);
-
-Route::prefix($routePrefix)
-    ->middleware($middleware)
+Route::prefix(config('pertuk.route_prefix', 'docs'))
+    ->middleware(config('pertuk.middleware', []))
     ->name('pertuk.docs.')
     ->group(function () {
-        $controller = DocumentController::class;
-
-        // Redirect root /docs to default locale
-        Route::get('/', function () {
-            $default = config('pertuk.default_locale', 'en');
-            // If default version is set, we might want to include it, but let's stick to locale/slug for now
-            // or redirect to the most "canonical" starting point.
-            // For now, mirroring existing behavior but cleaner.
-
-            return redirect()->route(config('pertuk.route_prefix', 'docs').'.show', [
-                'locale' => $default,
-                'slug' => 'index',
-            ]);
-        })->name('index');
-
-        $supportedLocales = (array) config('pertuk.supported_locales', ['en']);
-        $localeConstraint = implode('|', $supportedLocales);
-        $versionConstraint = '(?!('.$localeConstraint.')$)[a-zA-Z0-9\.]+';
-
-        // Search routes
-        Route::controller($controller)->group(function () use ($localeConstraint, $versionConstraint) {
+        $locales = implode('|', (array) config('pertuk.supported_locales', ['en']));
+        $version = '(?!('.$locales.')$)[a-zA-Z0-9\.]+';
+
+        Route::controller(DocumentController::class)->group(function () use ($locales, $version) {
+            // Root redirect
+            Route::get('/', 'root')->name('index');
+
+            // Search index
             Route::get('/{locale}/index.json', 'searchIndex')
-                ->where('locale', $localeConstraint)
+                ->where('locale', $locales)
                 ->name('search.json');
 
             Route::get('/{version}/{locale}/index.json', 'searchIndex')
-                ->where('version', $versionConstraint)
-                ->where('locale', $localeConstraint)
+                ->where('version', $version)
+                ->where('locale', $locales)
                 ->name('version.search.json');
 
-            // Documentation routes
-            // Note: Order matters. Versioned route first.
+            // Documentation pages
             Route::get('/{version}/{locale}/{slug?}', 'show')
-                ->where('version', $versionConstraint)
-                ->where('locale', $localeConstraint)
+                ->where('version', $version)
+                ->where('locale', $locales)
                 ->where('slug', '.*')
                 ->name('version.show');
 
             Route::get('/{locale}/{slug?}', 'show')
-                ->where('locale', $localeConstraint)
+                ->where('locale', $locales)
                 ->where('slug', '.*')
                 ->name('show');
         });

src/Http/Controllers/DocumentController.php

@@ -1,8 +1,15 @@
 <?php
 
+declare(strict_types=1);
+
 namespace Xoshbin\Pertuk\Http\Controllers;
 
+use Illuminate\Contracts\Filesystem\FileNotFoundException;
+use Illuminate\Contracts\View\View as ViewContract;
+use Illuminate\Http\JsonResponse;
+use Illuminate\Http\RedirectResponse;
 use Illuminate\Http\Request;
+use Illuminate\Http\Response as HttpResponse;
 use Illuminate\Routing\Controller;
 use Illuminate\Support\Facades\App;
 use Illuminate\Support\Facades\Session;
@@ -11,7 +18,24 @@
 
 class DocumentController extends Controller
 {
-    public function show(Request $request): \Illuminate\Http\Response|\Illuminate\Contracts\View\View|\Illuminate\Http\RedirectResponse
+    /**
+     * Redirect root to default locale.
+     */
+    public function root(): RedirectResponse
+    {
+        $default = config('pertuk.default_locale', 'en');
+        $prefix = config('pertuk.route_prefix', 'docs');
+
+        return redirect()->route($prefix.'.show', [
+            'locale' => $default,
+            'slug' => 'index',
+        ]);
+    }
+
+    /**
+     * Show a documentation page.
+     */
+    public function show(Request $request): HttpResponse|ViewContract|RedirectResponse
     {
         // Session starting should ideally be in middleware, leaving it for now if middleware is minimal.
         if (! Session::isStarted()) {
@@ -22,8 +46,13 @@ public function show(Request $request): \Illuminate\Http\Response|\Illuminate\Co
         $locale = $request->route('locale');
         $slug = $request->route('slug') ?? 'index';
 
+        $locale = is_string($locale) ? $locale : 'en';
+        $slug = is_string($slug) ? $slug : 'index';
+        $version = is_string($version) ? $version : null;
+
         // Validation - 404 if locale not supported
-        abort_unless(in_array($locale, config('pertuk.supported_locales', ['en'])), 404);
+        $supportedLocales = (array) config('pertuk.supported_locales', ['en']);
+        abort_unless(in_array($locale, $supportedLocales, true), 404);
 
         // Set application locale state
         App::setLocale($locale);
@@ -34,7 +63,7 @@ public function show(Request $request): \Illuminate\Http\Response|\Illuminate\Co
         // Attempt to retrieve the document
         try {
             $data = $docs->get($locale, $slug);
-        } catch (\Illuminate\Contracts\Filesystem\FileNotFoundException $e) {
+        } catch (FileNotFoundException) {
             // Fallback: If 'index' is requested but no physical index.md exists,
             // we render the index view with a list of all documents.
             if ($slug === 'index') {
@@ -52,15 +81,15 @@ public function show(Request $request): \Illuminate\Http\Response|\Illuminate\Co
 
         return $this->responseWithCacheHeaders(
             response()->view('pertuk::show', $viewData),
-            $data['mtime'],
-            $data['etag']
+            (int) $data['mtime'],
+            (string) $data['etag']
         );
     }
 
     /**
-     * Render the index page with grouped documentation items.
+     * Helper to show the index page when index.md is missing.
      */
-    protected function showIndex(DocumentationService $docs, string $locale): \Illuminate\Contracts\View\View
+    protected function showIndex(DocumentationService $docs, string $locale): ViewContract
     {
         $items = $docs->list($locale);
 
@@ -81,7 +110,7 @@ protected function showIndex(DocumentationService $docs, string $locale): \Illum
     /**
      * Attach HTTP caching headers to the response.
      */
-    protected function responseWithCacheHeaders(\Illuminate\Http\Response $response, int $mtime, string $etag): \Illuminate\Http\Response
+    protected function responseWithCacheHeaders(HttpResponse $response, int $mtime, string $etag): HttpResponse
     {
         $lastModified = gmdate('D, d M Y H:i:s', $mtime).' GMT';
 
@@ -102,9 +131,14 @@ protected function responseWithCacheHeaders(\Illuminate\Http\Response $response,
         ]);
     }
 
-    public function searchIndex(Request $request, string $locale): \Illuminate\Http\JsonResponse
+    /**
+     * Search index endpoint.
+     */
+    public function searchIndex(Request $request, string $locale): JsonResponse
     {
         $version = $request->route('version');
+        $version = is_string($version) ? $version : null;
+
         $items = DocumentationService::make($version)->buildIndex($locale);
 
         return response()->json($items)->header('Content-Type', 'application/json');

src/Http/Controllers/LocaleController.php

@@ -1,5 +1,7 @@
 <?php
 
+declare(strict_types=1);
+
 namespace Xoshbin\Pertuk\Http\Controllers;
 
 use Illuminate\Http\JsonResponse;
@@ -9,12 +11,10 @@
 use Illuminate\Routing\Controller;
 use Illuminate\Support\Facades\App;
 use Illuminate\Support\Facades\Session;
+use Xoshbin\Pertuk\Services\DocumentationService;
 
 class LocaleController extends Controller
 {
-    /**
-     * Set the application locale and store it in session.
-     */
     /**
      * Set the application locale and store it in session.
      */
@@ -44,7 +44,7 @@ public function setLocale(Request $request, string $locale): Response|JsonRespon
         // Standard redirection
         $redirectUrl = $request->get('redirect') ?: $request->header('referer');
 
-        if ($redirectUrl && $this->isDocsUrl($redirectUrl)) {
+        if ($redirectUrl && is_string($redirectUrl) && $this->isDocsUrl($redirectUrl)) {
             return redirect($this->getLocaleEquivalentUrl($redirectUrl, $locale));
         }
 
@@ -68,7 +68,7 @@ protected function isDocsUrl(string $url): bool
     protected function getLocaleEquivalentUrl(string $url, string $locale): string
     {
         $docsPrefix = config('pertuk.route_prefix', 'docs');
-        $versions = \Xoshbin\Pertuk\Services\DocumentationService::getAvailableVersions();
+        $versions = DocumentationService::getAvailableVersions();
 
         // Parse path from URL
         $path = parse_url($url, PHP_URL_PATH) ?? '/';
@@ -77,10 +77,7 @@ protected function getLocaleEquivalentUrl(string $url, string $locale): string
         $segments = explode('/', $path);
 
         // Find where the docs prefix ends.
-        // We assume the prefix is at the start of the path relative to the domain root.
-        // If the app is in a subdirectory, this logic might need adjustment, but for now assuming standard setup.
-
-        $prefixSegments = explode('/', $docsPrefix);
+        $prefixSegments = explode('/', (string) $docsPrefix);
         $remainder = array_slice($segments, count($prefixSegments));
 
         if (empty($remainder)) {
@@ -90,7 +87,7 @@ protected function getLocaleEquivalentUrl(string $url, string $locale): string
         // Check structure: [version, locale, slug...] or [locale, slug...]
         $first = $remainder[0];
 
-        if (in_array($first, $versions)) {
+        if (in_array($first, $versions, true)) {
             // Versioned URL: /docs/{version}/{locale}/{slug}
             // Replace the second segment (locale)
             if (isset($remainder[1])) {