# Error Handling

PHPFast manages errors using the `AppException` class, located in `system/Core/AppException.php`. This class extends PHP’s built-in `Exception` class and provides error logging, custom error pages, and detailed error messages based on the application’s debug mode.

***

## **How `AppException` Works**

The `AppException` class helps handle errors efficiently by providing:

**Custom error messages** – Define clear and readable error descriptions.\
**Automatic error logging** – Uses the Logger library to record error details.\
**User-friendly error display** – Shows helpful messages based on debug settings.\
**Custom error pages** – Automatically renders pages like 404 Not Found or 500 Server Error based on the error type.

By using `AppException`, you can keep your application stable, log important issues, and show meaningful error messages to users. 

## Handling Errors

You can manage errors in your application by **throwing an exception** using the `AppException` class:

**Throwing an Exception**

```php
throw new \System\Core\AppException('An error occurred!', 0, null, 500);
```

**Catching and Handling the Exception**

```php
try {
    // Code that might cause an error
} catch (\System\Core\AppException $e) {
    $e->handle(); // Process the exception
}
```

## Custom Error Pages

The `AppException` class automatically renders custom error pages based on the error status code. For example, when a 404 error occurs, the `render404()` method is called, which loads the **404 error page** from the themes directory using the Render library.

## Automatic Error Logging

All errors are recorded using the `Logger` class. When an exception is handled, the `handle()` method automatically calls `Logger::error()`, logging details such as: Error message**,** File location, Line number.

## Debug Mode

When debug mode is enabled (`config('app')['debug'] = true`) → The system displays detailed error information, including: **Error message, File location**, **Line number** and **Stack trace**

When debug mode is disabled → A generic error message is shown to users, preventing sensitive system details from being exposed.

## Usage in a Controller

```php
<?php
namespace App\Controllers;

use System\Core\BaseController;
use System\Core\AppException;

class UserController extends BaseController {

    public function index() {
        try {
            // Simulate an error (e.g., user not found)
            $user = $this->findUserById(1);
            if (!$user) {
                throw new AppException('User not found!', 0, null, 404);
            }

            // Render the user data
            $this->render('user/profile', ['user' => $user]);

        } catch (AppException $e) {
            // Handle the exception
            $e->handle();
        }
    }

    private function findUserById($id) {
        // Sample method to simulate user fetching; returns null to simulate "user not found"
        return null;
    }
}
```

**How It Works:**

* `try {}` → Starts the error-handling block.
* Attempts to find the user using `findUserById(1)`.
* If the user is not found (`null`), throws an **AppException** with the message `"User not found!"` and error code `404`.
* If no error occurs, **renders the user profile page** using `render('user/profile', ['user' => $user])`.
* `catch (AppException $e) {}` → If an error occurs, it is handled by calling `$e->handle();`, which may log the error or display an error page.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.cmsfullform.com/documents/libraries/error-handling.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.