# Image Storage Setup Guide

This guide explains how to set up and troubleshoot image storage in the Real Estate Management System.

## Quick Fix

If images are not displaying, run these commands:

```bash
# 1. Create the storage link (if it doesn't exist)
php artisan storage:link

# 2. Check storage link status
php artisan storage:check

# 3. Fix storage link if needed
php artisan storage:check --fix

# 4. Ensure storage directory has correct permissions
chmod -R 775 storage
chmod -R 775 public/storage
```

## Storage Structure

```
storage/
└── app/
    └── public/
        ├── properties/          # Property images
        ├── logos/              # System logos and favicons
        └── companies/
            └── logos/          # Company logos
```

## How Images Work

### 1. Image Upload
- Images are uploaded via controllers (PropertyController, AppearanceController, etc.)
- Files are stored in `storage/app/public/` using Laravel's Storage facade
- Paths are saved in the database (e.g., `properties/image123.jpg`)

### 2. Image Display
- Images are accessed via the `ImageHelper` class or model accessors
- The helper checks if files exist and provides fallback placeholders
- URLs are generated using `Storage::url()` or `asset('storage/...')`

### 3. Storage Link
- Laravel creates a symbolic link from `public/storage` to `storage/app/public`
- This allows public access to stored files without exposing the storage directory
- The link must exist for images to display correctly

## Troubleshooting

### Images Not Displaying

**Problem:** Images upload successfully but don't appear on the frontend.

**Solutions:**

1. **Check if storage link exists:**
   ```bash
   php artisan storage:check
   ```

2. **Create storage link:**
   ```bash
   php artisan storage:link
   ```

3. **On Windows (if symlink fails):**
   - Run Command Prompt as Administrator
   - Execute: `mklink /D "C:\path\to\project\public\storage" "C:\path\to\project\storage\app\public"`

4. **Check file permissions:**
   ```bash
   # Linux/Mac
   chmod -R 775 storage
   chmod -R 775 public/storage
   
   # Ensure web server can write
   sudo chown -R www-data:www-data storage
   sudo chown -R www-data:www-data public/storage
   ```

5. **Verify APP_URL in .env:**
   ```env
   APP_URL=http://localhost:8000
   ```

6. **Clear cache:**
   ```bash
   php artisan config:clear
   php artisan cache:clear
   php artisan view:clear
   ```

### Storage Link Issues on Windows

Windows requires administrator privileges to create symbolic links.

**Option 1: Run as Administrator**
```bash
# Right-click Command Prompt/PowerShell → Run as Administrator
php artisan storage:link
```

**Option 2: Use Junction (Windows alternative)**
```bash
# Install Junction from Sysinternals, then:
junction public\storage storage\app\public
```

**Option 3: Manual Link Creation**
1. Open Command Prompt as Administrator
2. Navigate to project root
3. Run: `mklink /D public\storage storage\app\public`

### Images Upload But Return 404

**Problem:** Files upload but return 404 when accessed.

**Solutions:**

1. **Verify storage link points to correct location:**
   ```bash
   php artisan storage:check
   ```

2. **Check if files actually exist:**
   ```bash
   ls -la storage/app/public/properties/
   ```

3. **Verify web server can access the link:**
   - Check `public/storage` directory exists
   - Verify it's a symlink, not a regular directory

4. **Check .htaccess (Apache):**
   Ensure `public/.htaccess` allows following symlinks:
   ```apache
   Options +FollowSymLinks
   ```

### Permission Denied Errors

**Problem:** Cannot upload images due to permission errors.

**Solutions:**

1. **Set correct permissions:**
   ```bash
   chmod -R 775 storage
   chmod -R 775 bootstrap/cache
   ```

2. **Set correct ownership (Linux):**
   ```bash
   sudo chown -R www-data:www-data storage
   sudo chown -R www-data:www-data bootstrap/cache
   ```

3. **Check SELinux (if enabled):**
   ```bash
   sudo chcon -R -t httpd_sys_rw_content_t storage
   ```

## Image Helper Usage

The `ImageHelper` class provides consistent image URL generation:

```php
use App\Helpers\ImageHelper;

// Get image URL
$url = ImageHelper::url($imagePath);

// Get image URL with fallback
$url = ImageHelper::url($imagePath, 'path/to/fallback.jpg');

// Check if image exists
if (ImageHelper::exists($imagePath)) {
    // Image exists
}

// Delete image
ImageHelper::delete($imagePath);
```

## Model Accessors

Models provide convenient accessors:

```php
// PropertyImage
$image->url;              // Full URL to image
$image->asset_url;        // Asset URL (backward compatible)
$image->exists();         // Check if file exists

// Property
$property->primary_image_url;  // URL to primary image or placeholder
```

## Testing Image Display

1. **Upload a test image** via admin panel
2. **Check database** - verify path is saved correctly
3. **Check file system** - verify file exists in storage
4. **Check storage link** - verify symlink exists
5. **Access URL directly** - test if image loads
6. **Check browser console** - look for 404 errors

## Production Deployment

For production servers:

1. **Create storage link:**
   ```bash
   php artisan storage:link
   ```

2. **Set permissions:**
   ```bash
   chmod -R 755 storage
   chmod -R 755 public/storage
   ```

3. **Optimize:**
   ```bash
   php artisan config:cache
   php artisan route:cache
   php artisan view:cache
   ```

4. **Consider CDN:**
   - For better performance, use S3 or CDN
   - Update `config/filesystems.php` to use S3 driver
   - Update `.env` with S3 credentials

## Support

If issues persist:
1. Check Laravel logs: `storage/logs/laravel.log`
2. Check web server error logs
3. Verify file paths in database match actual files
4. Test with a simple image upload