adds mvc events.

Author: ljonesfl

src/Mvc/Application.php

@@ -229,6 +229,19 @@ protected function onStart(): bool
 	 */
 	protected function onRun() : void
 	{
+		// Emit request received event
+		$params = $this->getParameters();
+		$method = $params['REQUEST_METHOD'] ?? 'GET';
+		$route = $params['REQUEST_URI'] ?? '/';
+		$ip = $_SERVER['REMOTE_ADDR'] ?? 'unknown';
+
+		\Neuron\Application\CrossCutting\Event::emit( new Events\RequestReceivedEvent(
+			$method,
+			$route,
+			$ip,
+			microtime( true )
+		) );
+
 		$output = $this->_router->run( $this->getParameters() );
 
 		if( !$this->_captureOutput )

src/Mvc/Events/RateLimitExceededEvent.php

@@ -0,0 +1,47 @@
+<?php
+
+namespace Neuron\Mvc\Events;
+
+use Neuron\Events\IEvent;
+
+/**
+ * Event fired when a request exceeds rate limit thresholds.
+ *
+ * This event is triggered by the RateLimitFilter when a client (identified
+ * by IP address or other key) exceeds the configured rate limit for a route
+ * or API endpoint.
+ *
+ * Use cases:
+ * - Security monitoring and abuse detection
+ * - Automatically block or throttle abusive IPs
+ * - Alert administrators of potential DDoS attacks
+ * - Track rate limit patterns and adjust thresholds
+ * - Generate security reports for compliance
+ * - Trigger CAPTCHA challenges for suspicious traffic
+ *
+ * @package Neuron\Mvc\Events
+ */
+class RateLimitExceededEvent implements IEvent
+{
+	/**
+	 * @param string $ip Client IP address that exceeded the limit
+	 * @param string $route Route or endpoint that was rate limited
+	 * @param int $limit Maximum requests allowed
+	 * @param int $window Time window in seconds
+	 * @param int $attempts Number of requests made in the window
+	 */
+	public function __construct(
+		public readonly string $ip,
+		public readonly string $route,
+		public readonly int $limit,
+		public readonly int $window,
+		public readonly int $attempts
+	)
+	{
+	}
+
+	public function getName(): string
+	{
+		return 'rate_limit.exceeded';
+	}
+}

src/Mvc/Events/RequestReceivedEvent.php

@@ -0,0 +1,44 @@
+<?php
+
+namespace Neuron\Mvc\Events;
+
+use Neuron\Events\IEvent;
+
+/**
+ * Event fired when the MVC application receives an HTTP request.
+ *
+ * This event is triggered at the beginning of the request lifecycle,
+ * before routing and controller execution.
+ *
+ * Use cases:
+ * - Request logging and analytics
+ * - Track request volume and patterns
+ * - Implement custom request filtering or preprocessing
+ * - Generate audit trails for compliance
+ * - Monitor API usage and endpoints
+ * - Track user behavior and navigation patterns
+ *
+ * @package Neuron\Mvc\Events
+ */
+class RequestReceivedEvent implements IEvent
+{
+	/**
+	 * @param string $method HTTP method (GET, POST, PUT, DELETE, etc.)
+	 * @param string $route Requested route/path
+	 * @param string $ip Client IP address
+	 * @param float $timestamp Request timestamp (microtime)
+	 */
+	public function __construct(
+		public readonly string $method,
+		public readonly string $route,
+		public readonly string $ip,
+		public readonly float $timestamp
+	)
+	{
+	}
+
+	public function getName(): string
+	{
+		return 'request.received';
+	}
+}

src/Mvc/Events/ViewCacheHitEvent.php

@@ -0,0 +1,42 @@
+<?php
+
+namespace Neuron\Mvc\Events;
+
+use Neuron\Events\IEvent;
+
+/**
+ * Event fired when a rendered view is served from cache.
+ *
+ * This event is triggered when the view caching system finds a valid
+ * cached version of the requested view and returns it without rendering.
+ *
+ * Use cases:
+ * - Monitor cache effectiveness and hit rates
+ * - Track performance improvements from caching
+ * - Identify which pages benefit most from caching
+ * - Optimize cache TTL based on hit patterns
+ * - Generate cache performance reports
+ * - Debug caching behavior and cache key generation
+ *
+ * @package Neuron\Mvc\Events
+ */
+class ViewCacheHitEvent implements IEvent
+{
+	/**
+	 * @param string $controller Controller name
+	 * @param string $page Page/view name
+	 * @param string $cacheKey Cache key used for lookup
+	 */
+	public function __construct(
+		public readonly string $controller,
+		public readonly string $page,
+		public readonly string $cacheKey
+	)
+	{
+	}
+
+	public function getName(): string
+	{
+		return 'view.cache_hit';
+	}
+}

src/Mvc/Events/ViewCacheMissEvent.php

@@ -0,0 +1,42 @@
+<?php
+
+namespace Neuron\Mvc\Events;
+
+use Neuron\Events\IEvent;
+
+/**
+ * Event fired when a view must be rendered because no cache exists.
+ *
+ * This event is triggered when the view caching system does not find a
+ * cached version of the requested view, requiring a full render.
+ *
+ * Use cases:
+ * - Monitor cache miss rates and efficiency
+ * - Identify pages that should be cached but aren't
+ * - Track cold cache scenarios after deployment or cache clear
+ * - Measure rendering performance on cache misses
+ * - Optimize cache warming strategies
+ * - Debug cache key generation and TTL issues
+ *
+ * @package Neuron\Mvc\Events
+ */
+class ViewCacheMissEvent implements IEvent
+{
+	/**
+	 * @param string $controller Controller name
+	 * @param string $page Page/view name
+	 * @param string $cacheKey Cache key that was not found
+	 */
+	public function __construct(
+		public readonly string $controller,
+		public readonly string $page,
+		public readonly string $cacheKey
+	)
+	{
+	}
+
+	public function getName(): string
+	{
+		return 'view.cache_miss';
+	}
+}

src/Mvc/Views/CacheableView.php

@@ -84,6 +84,24 @@ protected function getCachedContent( string $key ): ?string
 			try
 			{
 				$content = $cache->get( $key );
+
+				// Emit cache hit or miss event
+				if( $content !== null )
+				{
+					\Neuron\Application\CrossCutting\Event::emit( new \Neuron\Mvc\Events\ViewCacheHitEvent(
+						$this->getController(),
+						$this->getPage(),
+						$key
+					) );
+				}
+				else
+				{
+					\Neuron\Application\CrossCutting\Event::emit( new \Neuron\Mvc\Events\ViewCacheMissEvent(
+						$this->getController(),
+						$this->getPage(),
+						$key
+					) );
+				}
 			}
 			finally
 			{
@@ -98,7 +116,27 @@ protected function getCachedContent( string $key ): ?string
 		}
 
 		// Otherwise use normal cache method which checks global setting
-		return $cache->get( $key );
+		$content = $cache->get( $key );
+
+		// Emit cache hit or miss event
+		if( $content !== null )
+		{
+			\Neuron\Application\CrossCutting\Event::emit( new \Neuron\Mvc\Events\ViewCacheHitEvent(
+				$this->getController(),
+				$this->getPage(),
+				$key
+			) );
+		}
+		else
+		{
+			\Neuron\Application\CrossCutting\Event::emit( new \Neuron\Mvc\Events\ViewCacheMissEvent(
+				$this->getController(),
+				$this->getPage(),
+				$key
+			) );
+		}
+
+		return $content;
 	}
 
 	/**

versionlog.md

@@ -1,4 +1,5 @@
 ## 0.9.9
+* Added MVC events.
 
 ## 0.9.8 2025-11-24