# AGENT.md — Laravel Calculator Project

## Project Overview
This project is a lightweight calculator application built with Laravel 12.

Primary goals:
- Simple Arabic RTL calculator UI.
- Server-side calculation validation through Laravel.
- No database dependency.
- Session-based calculation history.
- Easy deployment on shared hosting / cPanel.
- Compatible with PHP 8.2+.

## Technology Stack
- PHP 8.2+
- Laravel 12
- Blade
- Vanilla JavaScript
- HTML / CSS
- Laravel Session
- Composer

## Project Structure

Important files:

- `routes/web.php`
  - Defines calculator routes.

- `app/Http/Controllers/CalculatorController.php`
  - Handles calculator page.
  - Handles calculation requests.
  - Validates input.
  - Prevents division by zero.
  - Stores calculation history in session.

- `resources/views/calculator.blade.php`
  - Main calculator interface.
  - Arabic RTL layout.
  - Calculator buttons and keyboard support.

- `.env`
  - Application environment configuration.

## Functional Requirements

The calculator must support:

- Addition
- Subtraction
- Multiplication
- Division
- Percentage
- Decimal numbers
- Positive / negative values
- Clear
- Backspace
- Keyboard input
- Mobile-friendly layout
- Calculation history

## Business / Validation Rules

1. Never allow division by zero.
2. Validate all server-side calculation inputs.
3. Do not trust JavaScript-only validation.
4. Keep numeric precision reasonable and avoid unnecessary floating-point display noise.
5. Do not require MySQL or any database unless explicitly requested.
6. Calculation history should remain session-based unless requirements change.

## UI Rules

- Arabic interface.
- RTL layout.
- Use Arial where practical.
- Responsive on desktop and mobile.
- Keep the calculator compact and clear.
- Do not introduce unnecessary UI libraries.

## Development Rules

1. Discuss significant architectural changes before implementing them.
2. Do not add database migrations unless requested.
3. Do not replace the current calculator logic without understanding existing behavior.
4. Preserve current routes unless there is a clear reason to change them.
5. Keep controllers small and readable.
6. Prefer Laravel validation for incoming requests.
7. Avoid unnecessary packages.
8. Do not expose debug information in production.

## Security Rules

- Escape user-visible output.
- Validate request parameters.
- Keep CSRF protection enabled.
- Do not use `eval()` for calculator expressions.
- Do not execute arbitrary expressions supplied by users.
- Never expose `.env`.
- Production must use:
  - `APP_ENV=production`
  - `APP_DEBUG=false`

## Deployment Environment

Typical deployment target:
- cPanel shared hosting
- PHP 8.2+
- Project domain example:
  - `calcc.mylaundry.online`

Composer may not exist globally.

A local Composer installation can be used as:

```bash
php composer.phar
```

When `allow_url_fopen` is disabled for CLI PHP, enable it only for the required command:

```bash
php -d allow_url_fopen=1 composer-setup.php --filename=composer.phar
```

## Terminal Command Convention

All terminal commands provided to the project owner must begin with:

```bash
clear &&
```

Give only one clear terminal command at a time, then inspect the result before moving to the next step.

## Installation

Typical sequence:

```bash
php composer.phar install --no-dev --optimize-autoloader
```

Then configure `.env` and generate the application key if needed:

```bash
php artisan key:generate
```

Clear Laravel caches after configuration changes:

```bash
php artisan optimize:clear
```

## Laravel Writable Directories

The following directories must be writable by the web server:

- `storage`
- `bootstrap/cache`

Do not use unsafe `777` permissions unless there is no alternative and it is explicitly approved.

## Web Root

Preferred deployment:

The domain document root should point to:

```text
/public
```

Do not expose the Laravel project root directly to the public web.

## Testing Checklist

Before considering a deployment complete, verify:

- Application opens without HTTP 500.
- Calculator page loads correctly.
- Addition works.
- Subtraction works.
- Multiplication works.
- Division works.
- Division by zero is rejected safely.
- Decimal calculations work.
- Percentage works.
- Keyboard input works.
- Mobile layout works.
- Session history works.
- History clear action works.
- CSRF validation works.
- `APP_DEBUG=false` in production.

## Change Control

Before changing core behavior:
1. Identify the exact file.
2. Review current implementation.
3. Explain the intended change.
4. Back up the affected file when working on production.
5. Apply the smallest safe change.
6. Run syntax / application checks.
7. Clear relevant Laravel caches.
8. Verify behavior.

## PHP Syntax Check

For edited PHP files:

```bash
php -l path/to/file.php
```

## Important

Do not assume server capabilities.

Always verify:
- PHP version
- Required PHP extensions
- Composer availability
- Document root
- File permissions
- Laravel environment
- Writable directories

before making deployment changes.