url-rewriting

config/routing.yaml

@@ -0,0 +1,13 @@
+# Neuron CMS Routing Configuration (for CMS package development/testing)
+# This file is used when testing the CMS package itself
+
+# URL Rewrites
+# By default, the root path (/) is rewritten to /blog
+rewrites:
+  '/': '/blog'
+
+# Controller Paths
+# For CMS package development, point directly to src/Cms/Controllers
+controller_paths:
+  - path: 'src/Cms/Controllers'
+    namespace: 'Neuron\Cms\Controllers'

readme.md

@@ -104,7 +104,7 @@ The installer will:
 1. Create the complete directory structure (app/, config/, db/, public/, resources/, storage/)
 2. Publish all view templates (admin panel, blog, auth, layouts)
 3. Publish application initializers
-4. Create configuration files (neuron.yaml, routes.yaml, auth.yaml, event-listeners.yaml)
+4. Create configuration files (neuron.yaml, routing.yaml, auth.yaml, event-listeners.yaml)
 5. Generate the front controller (public/index.php)
 6. Set up database migrations
 7. Optionally run migrations to create database tables
@@ -136,7 +136,7 @@ your-project/
 │   ├── auth.yaml           # Authentication configuration
 │   ├── neuron.yaml         # Main application config
 │   ├── event-listeners.yaml # Event listener configuration
-│   └── routes.yaml         # Route definitions
+│   └── routing.yaml        # Routing configuration (URL rewrites, controller paths)
 │
 ├── db/
 │   ├── migrate/            # Database migrations
@@ -224,7 +224,7 @@ database:
   name: storage/database.sqlite3
 ```
 
-All routes, authentication settings, and event listeners are pre-configured by the installer.
+All routing, authentication settings, and event listeners are pre-configured by the installer.
 
 ## Usage
 
@@ -369,23 +369,74 @@ The installer creates `config/auth.yaml` with sensible defaults. You can customi
 - Failed login attempt limits
 - Account lockout duration
 
-### Routes
+### Routing
 
-The installer automatically creates `config/routes.yaml` with pre-configured routes for:
+The CMS uses attribute-based routing defined directly on controller methods. The installer creates `config/routing.yaml` to configure URL rewrites and controller paths.
 
-- Public blog pages (`/blog`, `/blog/article/{slug}`, `/blog/category/{slug}`, `/blog/tag/{slug}`)
-- Admin panel (`/admin/*`)
-- Authentication (`/login`, `/logout`)
-- Password reset (`/password/reset`, `/password/reset/confirm`)
-- Member registration and dashboard:
+#### URL Rewrites
+
+By default, the CMS rewrites the root URL (`/`) to `/blog`. You can customize this in `config/routing.yaml`:
+
+```yaml
+# config/routing.yaml
+rewrites:
+  '/': '/custom/landing'  # Rewrite root to your custom controller
+
+controller_paths:
+  - path: 'app/Controllers'        # Your controllers first (takes precedence)
+    namespace: 'App\Controllers'
+  - path: 'vendor/neuron-php/cms/src/Cms/Controllers'
+    namespace: 'Neuron\Cms\Controllers'
+```
+
+Then create your custom landing controller:
+
+```php
+// app/Controllers/Landing.php
+use Neuron\Mvc\Controller;
+use Neuron\Routing\Attributes\Get;
+
+class Landing extends Controller
+{
+    #[Get('/custom/landing', name: 'landing')]
+    public function index()
+    {
+        return $this->renderHtml(OK, [], 'custom-home');
+    }
+}
+```
+
+URL rewrites are transparent (no HTTP redirect) - the browser URL stays the same while the application routes to a different path internally.
+
+#### Available Routes
+
+The CMS provides these pre-configured routes via controller attributes:
+
+- **Public blog pages**:
+  - `/blog` - Blog listing
+  - `/blog/article/:slug` - Individual post
+  - `/blog/category/:slug` - Category listing
+  - `/blog/tag/:slug` - Tag listing
+  - `/blog/rss` - RSS feed
+
+- **Admin panel**: `/admin/*` - Full admin interface with authentication
+
+- **Authentication**:
+  - `/login` - Login form
+  - `/logout` - Logout handler
+
+- **Password reset**:
+  - `/password/reset` - Request reset form
+  - `/password/reset/confirm` - Reset confirmation
+
+- **Member registration and dashboard**:
   - `/register` - Registration form
   - `/verify-email` - Email verification
   - `/resend-verification` - Resend verification email (rate-limited)
   - `/member` - Member dashboard (requires authentication)
   - `/member/profile` - Profile management
-- RSS feed (`/blog/rss`)
 
-You can customize routes by editing `config/routes.yaml`.
+For more information about routing configuration, URL rewrites, and attribute-based routing, see the [MVC Routing Documentation](https://github.com/Neuron-PHP/mvc).
 
 ### Email
 

resources/config/neuron.yaml.example

@@ -6,10 +6,8 @@ system:
   timezone: UTC  # Server timezone (e.g., America/New_York, Europe/London, UTC)
   base_path: resources  # Base path for resources
 
-routing:
-  controller_paths:
-    - path: 'vendor/neuron-php/cms/src/Cms/Controllers'
-      namespace: 'Neuron\Cms\Controllers'
+# Routing configuration is now in config/routing.yaml
+# See routing.yaml for URL rewrites and controller path configuration
 
 logging:
   destination: \Neuron\Log\Destination\File  # Log destination class

resources/config/routing.yaml

@@ -0,0 +1,28 @@
+# Neuron CMS Routing Configuration
+# This file configures URL rewrites and controller scanning for the CMS
+
+# URL Rewrites
+# Transparent URL rewriting (no HTTP redirect) applied before route matching
+# By default, the root path (/) is rewritten to /blog
+rewrites:
+  '/': '/blog'
+
+# Controller Paths
+# Directories to scan for controller classes with route attributes
+# Order matters: controllers listed first take precedence for duplicate routes
+controller_paths:
+  # Application controllers - your custom controllers go here
+  - path: 'app/Controllers'
+    namespace: 'App\Controllers'
+
+  # CMS controllers - provides admin panel, blog, auth, etc.
+  - path: 'vendor/neuron-php/cms/src/Cms/Controllers'
+    namespace: 'Neuron\Cms\Controllers'
+
+# To customize the homepage:
+# 1. Create your own controller in app/Controllers with a route for the desired path (e.g., /home)
+# 2. Update the rewrite above to point '/' to your path
+#
+# Example: Custom homepage controller in app/Controllers/HomeController.php
+# rewrites:
+#   '/': '/home'  # Route to custom homepage

src/Cms/Cli/Commands/Install/InstallCommand.php

@@ -372,32 +372,26 @@ protected function createRouteConfig(): bool
 		// Copy .gitignore template first
 		$this->copyGitignoreTemplate();
 
-		$routeFile = $this->_projectPath . '/config/routes.yaml';
-		$resourceFile = $this->_componentPath . '/resources/config/routes.yaml';
+		$routingFile = $this->_projectPath . '/config/routing.yaml';
+		$resourceFile = $this->_componentPath . '/resources/config/routing.yaml';
 
-		// If routes.yaml doesn't exist, copy from resources
-		if( !file_exists( $routeFile ) && file_exists( $resourceFile ) )
+		// If routing.yaml doesn't exist, copy from resources
+		if( !file_exists( $routingFile ) && file_exists( $resourceFile ) )
 		{
-			if( copy( $resourceFile, $routeFile ) )
+			if( copy( $resourceFile, $routingFile ) )
 			{
-				$this->_messages[] = "Created: config/routes.yaml";
+				$this->_messages[] = "Created: config/routing.yaml";
 				return true;
 			}
 
-			$this->output->error( "  Failed to create routes.yaml" );
+			$this->output->error( "  Failed to create routing.yaml" );
 			return false;
 		}
 
-		// If routes.yaml exists, check if it has admin routes
-		if( file_exists( $routeFile ) )
+		// If routing.yaml exists, notify user
+		if( file_exists( $routingFile ) )
 		{
-			$content = file_get_contents( $routeFile );
-
-			if( strpos( $content, '/admin/dashboard' ) === false )
-			{
-				$this->_messages[] = "⚠️  Please add admin routes to config/routes.yaml";
-				$this->_messages[] = "   See resources/config/routes.yaml for reference";
-			}
+			$this->_messages[] = "✓ Routing config exists: config/routing.yaml";
 		}
 
 		return true;
@@ -882,18 +876,6 @@ protected function saveCompleteConfig( array $databaseConfig, array $appConfig,
 			'views' => [
 				'path' => 'resources/views'
 			],
-			'routing' => [
-				'controller_paths' => [
-					[
-						'path' => 'app/Controllers',
-						'namespace' => 'App\\Controllers'
-					],
-					[
-						'path' => 'vendor/neuron-php/cms/src/Cms/Controllers',
-						'namespace' => 'Neuron\\Cms\\Controllers'
-					]
-				]
-			],
 			'system' => [
 				'timezone' => $appConfig['timezone'],
 				'base_path' => $this->_projectPath