Fix subdirectory slim routing as a got fix for 5.22.0 (#7558)

## What Changed
<!-- Short summary - what and why (not how) -->

What Changed
Update SlimUtils::getBasePath() to auto-detect subdirectory from
Config.php
Combine $sRootPath with endpoint path (/api, /v2, /session, etc.)
Replace manual path parsing in session, external, and kiosk entry points
Add proper import statements to all Slim entry points
Update .htaccess documentation for subdirectory installations
Add import statement rules to copilot-instructions.md
Resolves routing 404 errors when ChurchCRM is installed in
subdirectories like /churchcrm5220/

## Type
<!-- Check one -->
- [ ] ✨ Feature
- [x] 🐛 Bug fix
- [ ] ♻️ Refactor
- [ ] 🏗️ Build/Infrastructure
- [ ] 🔒 Security

## Testing
<!-- How to verify this works -->

## Screenshots
<!-- Only for UI changes - drag & drop images here -->

## Security Check
<!-- Only check if applicable -->
- [ ] Introduces new input validation
- [ ] Modifies authentication/authorization
- [ ] Affects data privacy/GDPR

### Code Quality
- [ ] Database: Propel ORM only, no raw SQL
- [ ] No deprecated attributes (align, valign, nowrap, border,
cellpadding, cellspacing, bgcolor)
- [ ] Bootstrap CSS classes used
- [ ] All CSS bundled via webpack

## Pre-Merge
- [ ] Tested locally
- [ ] No new warnings
- [ ] Build passes
- [ ] Backward compatible (or migration documented)

Author: DawoudIO

src/.htaccess

@@ -3,11 +3,14 @@ Options -Indexes
 
 RewriteEngine On
 
-# Some hosts may require you to use the `RewriteBase` directive.
-# If you need to use the `RewriteBase` directive, it should be the
-# absolute physical path to the directory that contains this htaccess file.
-#
-# RewriteBase /
+# Automatically handle subdirectory installations
+# The RewriteRule will pass the matched path to index.php
+# ChurchCRM uses the $sRootPath from Config.php to handle subdirectories
+# 
+# NOTE: If you have issues with routing, you may need to set RewriteBase manually:
+# For root installation (/): RewriteBase /
+# For subdirectory (/churchcrm): RewriteBase /churchcrm
+# For subdirectory (/xyz): RewriteBase /xyz
 
 RewriteCond %{REQUEST_FILENAME} !-f
 RewriteRule ^(.*)$ index.php [QSA,L]

src/ChurchCRM/Slim/SlimUtils.php

@@ -2,15 +2,19 @@
 namespace ChurchCRM\Slim;
 
 use ChurchCRM\dto\Photo;
+use ChurchCRM\dto\SystemURLs;
 use ChurchCRM\Utils\LoggerUtils;
+use Exception;
+use Monolog\Handler\StreamHandler;
+use Monolog\Logger;
 use Psr\Http\Message\ResponseInterface as Response;
 use Psr\Http\Message\ServerRequestInterface as Request;
+use Slim\Exception\HttpMethodNotAllowedException;
 use Slim\Exception\HttpNotFoundException;
+use Slim\HttpCache\CacheProvider;
 use Slim\Interfaces\RouteInterface;
+use Slim\Psr7\Response as Psr7Response;
 use Slim\Routing\RouteContext;
-use Slim\HttpCache\CacheProvider;
-use Monolog\Logger;
-use Monolog\Handler\StreamHandler;
 use Throwable;
 
 
@@ -88,11 +92,33 @@ public static function setupErrorLogger($errorMiddleware)
     }
 
     /**
-     * Get Slim base path from environment or default
+     * Get Slim base path from environment or calculate from SystemURLs root path
+     * This ensures Slim routes work correctly whether installed at root (/) or in a subdirectory (/churchcrm)
+     * 
+     * @param string $endpoint The Slim application endpoint (/api or /v2) - REQUIRED
+     * @return string The complete base path including subdirectory if applicable
      */
-    public static function getBasePath($default = '/api')
+    public static function getBasePath(string $endpoint)
     {
-        return getenv('SLIM_BASE_PATH') ?: $default;
+        // Allow environment override for testing/special deployments
+        if ($envPath = getenv('SLIM_BASE_PATH')) {
+            return $envPath;
+        }
+        
+        // Get the root path from SystemURLs (configured in Config.php as $sRootPath)
+        // Examples: '' (root install), '/churchcrm', '/crm', etc.
+        try {
+            $rootPath = SystemURLs::getRootPath();
+            
+            // Combine root path with endpoint
+            // If root is empty string (installed at /), just return endpoint
+            // If root is /churchcrm, return /churchcrm/api or /churchcrm/v2
+            return $rootPath . $endpoint;
+        } catch (Exception $e) {
+            // If SystemURLs not initialized yet, fall back to endpoint only
+            // This shouldn't happen in normal operation but provides safety
+            return $endpoint;
+        }
     }
 
     /**
@@ -119,13 +145,13 @@ public static function registerDefaultJsonErrorHandler($errorMiddleware)
             bool $logErrorDetails
         ) use ($logger) {
             $logger->error($exception->getMessage(), ['exception' => $exception]);
-            $response = new \Slim\Psr7\Response();
+            $response = new Psr7Response();
 
             // Determine appropriate HTTP status code based on exception type
             $statusCode = 500;
-            if ($exception instanceof \Slim\Exception\HttpNotFoundException) {
+            if ($exception instanceof HttpNotFoundException) {
                 $statusCode = 404;
-            } elseif ($exception instanceof \Slim\Exception\HttpMethodNotAllowedException) {
+            } elseif ($exception instanceof HttpMethodNotAllowedException) {
                 $statusCode = 405;
             }
 

src/api/.htaccess

@@ -1,10 +1,13 @@
 RewriteEngine On
 
-# Some hosts may require you to use the `RewriteBase` directive.
-# If you need to use the `RewriteBase` directive, it should be the
-# absolute physical path to the directory that contains this htaccess file.
-#
-# RewriteBase /
+# Automatically handle subdirectory installations
+# The RewriteRule will pass the matched path to index.php
+# Slim will use the base path from Config.php ($sRootPath) to match routes correctly
+# 
+# NOTE: If you have issues with routing, you may need to set RewriteBase manually:
+# For root installation (/): RewriteBase /api
+# For subdirectory (/churchcrm): RewriteBase /churchcrm/api
+# For subdirectory (/xyz): RewriteBase /xyz/api
 
 RewriteCond %{REQUEST_FILENAME} !-f
 RewriteRule ^(.*)$ index.php [QSA,L]

src/api/index.php

@@ -1,20 +1,23 @@
 <?php
+
+require_once '../Include/Config.php';
+require_once __DIR__ . '/../vendor/autoload.php';
+
 use ChurchCRM\Service\DepositService;
-use ChurchCRM\Slim\SlimUtils;
-use ChurchCRM\Slim\Middleware\AuthMiddleware;
-use ChurchCRM\Slim\Middleware\VersionMiddleware;
-use ChurchCRM\Slim\Middleware\CorsMiddleware;
 use ChurchCRM\Service\FinancialService;
 use ChurchCRM\Service\GroupService;
 use ChurchCRM\Service\PersonService;
 use ChurchCRM\Service\SystemService;
+use ChurchCRM\Slim\Middleware\AuthMiddleware;
+use ChurchCRM\Slim\Middleware\CorsMiddleware;
+use ChurchCRM\Slim\Middleware\VersionMiddleware;
+use ChurchCRM\Slim\SlimUtils;
 use Slim\Factory\AppFactory;
 use Symfony\Component\DependencyInjection\ContainerBuilder;
 
-require_once '../Include/Config.php';
-require_once __DIR__ . '/../vendor/autoload.php';
-
-// Use SlimUtils to get base path, default to /api
+// Get base path by combining $sRootPath from Config.php with /api endpoint
+// Examples: '' + '/api' = '/api' (root install)
+//           '/churchcrm' + '/api' = '/churchcrm/api' (subdirectory install)
 $basePath = SlimUtils::getBasePath('/api');
 
 

src/external/index.php

@@ -1,22 +1,25 @@
 <?php
 
-use ChurchCRM\Slim\SlimUtils;
-use ChurchCRM\Slim\Middleware\VersionMiddleware;
+require_once '../Include/Config.php';
+require_once __DIR__ . '/../vendor/autoload.php';
+
 use ChurchCRM\Slim\Middleware\CorsMiddleware;
+use ChurchCRM\Slim\Middleware\VersionMiddleware;
+use ChurchCRM\Slim\SlimUtils;
 use Slim\Factory\AppFactory;
 use Symfony\Component\DependencyInjection\ContainerBuilder;
 
-require_once '../Include/Config.php';
-require_once __DIR__ . '/../vendor/autoload.php';
-
-$rootPath = str_replace('/external/index.php', '', $_SERVER['SCRIPT_NAME']);
+// Get base path by combining $sRootPath from Config.php with /external endpoint
+// Examples: '' + '/external' = '/external' (root install)
+//           '/churchcrm' + '/external' = '/churchcrm/external' (subdirectory install)
+$basePath = SlimUtils::getBasePath('/external');
 
 
 $container = new ContainerBuilder();
 $container->compile();
 AppFactory::setContainer($container);
 $app = AppFactory::create();
-$app->setBasePath($rootPath . '/external');
+$app->setBasePath($basePath);
 
 // Add Slim error middleware for proper error handling and logging
 $errorMiddleware = $app->addErrorMiddleware(true, true, true);

src/kiosk/index.php

@@ -5,27 +5,31 @@
 // This file is generated by Composer
 require_once __DIR__ . '/../vendor/autoload.php';
 
-$rootPath = dirname($_SERVER['SCRIPT_NAME']);
 use ChurchCRM\dto\SystemConfig;
 use ChurchCRM\model\ChurchCRM\KioskDevice;
 use ChurchCRM\model\ChurchCRM\KioskDeviceQuery;
-use Slim\Factory\AppFactory;
-use Symfony\Component\DependencyInjection\ContainerBuilder;
 use ChurchCRM\Slim\Middleware\AuthMiddleware;
-use ChurchCRM\Slim\Middleware\VersionMiddleware;
 use ChurchCRM\Slim\Middleware\CorsMiddleware;
+use ChurchCRM\Slim\Middleware\VersionMiddleware;
 use ChurchCRM\Slim\SlimUtils;
+use Slim\Factory\AppFactory;
+use Symfony\Component\DependencyInjection\ContainerBuilder;
+
+// Get base path by combining $sRootPath from Config.php with /kiosk endpoint
+// Examples: '' + '/kiosk' = '/kiosk' (root install)
+//           '/churchcrm' + '/kiosk' = '/churchcrm/kiosk' (subdirectory install)
+$basePath = SlimUtils::getBasePath('/kiosk');
 
 $container = new ContainerBuilder();
 // Register custom error handlers
 AppFactory::setContainer($container);
 $app = AppFactory::create();
-$app->setBasePath($rootPath . '/kiosk');
+$app->setBasePath($basePath);
 
 // Add Slim error middleware for proper error handling and logging
 $errorMiddleware = $app->addErrorMiddleware(true, true, true);
-\ChurchCRM\Slim\SlimUtils::setupErrorLogger($errorMiddleware);
-\ChurchCRM\Slim\SlimUtils::registerDefaultJsonErrorHandler($errorMiddleware);
+SlimUtils::setupErrorLogger($errorMiddleware);
+SlimUtils::registerDefaultJsonErrorHandler($errorMiddleware);
 
 $app->addBodyParsingMiddleware();
 $app->addRoutingMiddleware();

src/session/index.php

@@ -17,14 +17,17 @@
 
 require_once __DIR__ . '/../vendor/autoload.php';
 
-$rootPath = str_replace('/session/index.php', '', $_SERVER['SCRIPT_NAME']);
+// Get base path by combining $sRootPath from Config.php with /session endpoint
+// Examples: '' + '/session' = '/session' (root install)
+//           '/churchcrm' + '/session' = '/churchcrm/session' (subdirectory install)
+$basePath = SlimUtils::getBasePath('/session');
 
 $container = new ContainerBuilder();
 $container->compile();
 // Register custom error handlers
 AppFactory::setContainer($container);
 $app = AppFactory::create();
-$app->setBasePath($rootPath . '/session');
+$app->setBasePath($basePath);
 
 // Add Slim error middleware for proper error handling and logging
 $errorMiddleware = $app->addErrorMiddleware(true, true, true);

src/setup/index.php

@@ -15,9 +15,11 @@
 
 require_once __DIR__ . '/../vendor/autoload.php';
 
-// Use SlimUtils to get base path, default to /setup
+// Use SlimUtils to get base path for routing, but assets are in parent directory
 $basePath = ChurchCRM\Slim\SlimUtils::getBasePath('/setup');
-SystemURLs::init($basePath, '', __DIR__ . '/../');
+// Initialize SystemURLs with parent directory root (where assets actually are)
+$parentRootPath = str_replace('/setup', '', $basePath);
+SystemURLs::init($parentRootPath, '', __DIR__ . '/../');
 SystemConfig::init();
 
 

src/setup/routes/setup.php

@@ -142,5 +142,6 @@ function is_valid_port($value)
 
 function is_valid_root_path($value)
 {
-    return preg_match('#^\/[a-zA-Z0-9_\-\.\/]*$#', $value);
+    // Allow empty string OR a path starting with / (no trailing slash)
+    return preg_match('#^(|\/[a-zA-Z0-9_\-\.\/]*)$#', $value);
 }

src/v2/.htaccess

@@ -1,9 +1,13 @@
 RewriteEngine On
 
-# Some hosts may require you to use the `RewriteBase` directive.
-# If you need to use the `RewriteBase` directive, it should be the
-# absolute physical path to the directory that contains this htaccess file.
-#
-# RewriteBase /
+# Automatically handle subdirectory installations
+# The RewriteRule will pass the matched path to index.php
+# Slim will use the base path from Config.php ($sRootPath) to match routes correctly
+# 
+# NOTE: If you have issues with routing, you may need to set RewriteBase manually:
+# For root installation (/): RewriteBase /v2
+# For subdirectory (/churchcrm): RewriteBase /churchcrm/v2
+# For subdirectory (/xyz): RewriteBase /xyz/v2
+
 RewriteCond %{REQUEST_FILENAME} !-f
 RewriteRule ^(.*)$ index.php [QSA,L]