# ============================================================
# Shakil's Homes — Flat Management System
# cPanel Shared Hosting Installation Guide
# Laravel 11 + MySQL + PHP 8.2+
# ============================================================

## PRE-REQUIREMENTS (Check with host)
- PHP >= 8.2
- MySQL >= 5.7 / MariaDB >= 10.3
- Composer (or upload vendor/)
- mod_rewrite enabled
- php_intl, php_mbstring, php_pdo_mysql extensions


━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
STEP 1 — CREATE DATABASE IN cPANEL
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

1. Login to cPanel → MySQL® Databases

2. Create Database:
   Database Name: your_cpanel_username_shakils

3. Create Database User:
   Username: your_cpanel_username_admin
   Password: [choose strong password]

4. Add User to Database → Grant ALL PRIVILEGES

5. Import SQL:
   Go to phpMyAdmin → Select database → Import tab
   → Upload: shakils_homes.sql
   → Click "Go"

   ✅ This creates all 8 tables + seeds demo data
   Default Admin: admin@shakilshomes.com / password


━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
STEP 2 — UPLOAD PROJECT FILES
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

METHOD A — File Manager (Recommended)

1. cPanel → File Manager → Go to /home/your_username/

2. Create folder: shakils-homes
   (This folder will be OUTSIDE public_html)

3. Upload the .zip file to /home/your_username/shakils-homes/
   → Right click → Extract

4. Your structure should be:
   /home/your_username/
   ├── shakils-homes/          ← Laravel app root
   │   ├── app/
   │   ├── bootstrap/
   │   ├── config/
   │   ├── database/
   │   ├── public/             ← only this goes to public_html
   │   ├── resources/
   │   ├── routes/
   │   ├── storage/
   │   ├── vendor/
   │   └── .env
   └── public_html/
       └── shakilshomes/       ← symlink / copy of public/

5. Copy contents of public/ to public_html/shakilshomes/
   (Or point subdomain directly to public/ folder)


METHOD B — Via Terminal/SSH (Faster)

  # Upload zip then:
  cd /home/your_username
  unzip shakils-homes.zip
  mv shakils-homes app

  # Point domain to public folder
  ln -s /home/your_username/app/public /home/your_username/public_html/shakilshomes


━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
STEP 3 — CONFIGURE .ENV FILE
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Edit /home/your_username/shakils-homes/.env

```env
APP_NAME="Shakil's Homes"
APP_ENV=production
APP_KEY=                          # Will be generated in Step 4
APP_DEBUG=false
APP_URL=https://yourdomain.com

LOG_CHANNEL=stack
LOG_LEVEL=error

DB_CONNECTION=mysql
DB_HOST=localhost
DB_PORT=3306
DB_DATABASE=your_cpanel_username_shakils   # From Step 1
DB_USERNAME=your_cpanel_username_admin     # From Step 1
DB_PASSWORD=your_database_password        # From Step 1

BROADCAST_DRIVER=log
CACHE_DRIVER=file
QUEUE_CONNECTION=sync
SESSION_DRIVER=file
SESSION_LIFETIME=120

MAIL_MAILER=smtp
MAIL_HOST=mail.yourdomain.com
MAIL_PORT=587
MAIL_USERNAME=info@yourdomain.com
MAIL_PASSWORD=your_email_password
MAIL_ENCRYPTION=tls
MAIL_FROM_ADDRESS=info@yourdomain.com
MAIL_FROM_NAME="Shakil's Homes"

FILESYSTEM_DISK=public
```


━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
STEP 4 — RUN SETUP COMMANDS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Via cPanel Terminal or SSH:

  cd /home/your_username/shakils-homes

  # 4a. Install PHP dependencies (if vendor/ not included)
  composer install --no-dev --optimize-autoloader

  # 4b. Generate application key
  php artisan key:generate

  # 4c. Run migrations + seed (if NOT using the SQL import)
  php artisan migrate --seed
  # (Skip if you already imported shakils_homes.sql)

  # 4d. Create storage symlink
  php artisan storage:link

  # 4e. Cache config for production speed
  php artisan config:cache
  php artisan route:cache
  php artisan view:cache

  # 4f. Set permissions
  chmod -R 755 storage/
  chmod -R 755 bootstrap/cache/
  chown -R your_username:your_username storage/
  chown -R your_username:your_username bootstrap/cache/


━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
STEP 5 — CONFIGURE PUBLIC_HTML / SUBDOMAIN
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

OPTION A — Point subdomain to /public (RECOMMENDED)

1. cPanel → Subdomains
2. Create: flats.yourdomain.com
3. Document Root: /home/your_username/shakils-homes/public
4. Click Create

✅ Visit https://flats.yourdomain.com to access the app


OPTION B — Main domain (replace public_html content)

Edit /home/your_username/shakils-homes/public/index.php
Change line 6 from:
  $app = require __DIR__.'/../bootstrap/app.php';
To point correctly to your app root.

Edit public/.htaccess to ensure correct paths.


OPTION C — Subdirectory (e.g. yourdomain.com/homes)

Copy public/ contents to public_html/homes/
Edit public_html/homes/index.php — update the paths:

```php
// Change these two lines:
require __DIR__.'/../../shakils-homes/vendor/autoload.php';
$app = require_once __DIR__.'/../../shakils-homes/bootstrap/app.php';
```


━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
STEP 6 — CONFIGURE .HTACCESS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Ensure public/.htaccess contains (Laravel default):

```apache
<IfModule mod_rewrite.c>
    <IfModule mod_negotiation.c>
        Options -MultiViews -Indexes
    </IfModule>

    RewriteEngine On

    # Handle Authorization Header
    RewriteCond %{HTTP:Authorization} .
    RewriteRule .* - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization}]

    # Redirect Trailing Slashes
    RewriteCond %{REQUEST_FILENAME} !-d
    RewriteCond %{REQUEST_URI} (.+)/$
    RewriteRule ^ %1 [L,R=301]

    # Send Requests To Front Controller
    RewriteCond %{REQUEST_FILENAME} !-d
    RewriteCond %{REQUEST_FILENAME} !-f
    RewriteRule ^ index.php [L]
</IfModule>
```


━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
STEP 7 — SETUP CRON JOB (Monthly Bill Auto-Generation)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

1. cPanel → Cron Jobs

2. Add cron (runs Laravel scheduler every minute):
   Minute: *
   Hour: *
   Day: *
   Month: *
   Weekday: *
   Command:
   /usr/local/bin/php /home/your_username/shakils-homes/artisan schedule:run >> /dev/null 2>&1

   This will auto-generate bills on the 1st of every month
   and mark overdue bills after the due date.

3. To test manually via SSH:
   php artisan bills:generate --month=2025-06


━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
STEP 8 — SSL CERTIFICATE
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

1. cPanel → SSL/TLS → Let's Encrypt SSL (free)
2. Issue for your domain/subdomain
3. Enable "Force HTTPS Redirect"


━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
STEP 9 — VERIFY INSTALLATION
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Visit: https://flats.yourdomain.com

✅ You should see the login page.

Test Credentials (from seeded data):

  ADMIN LOGIN:
  Email:    admin@shakilshomes.com
  Password: password

  TENANT LOGIN:
  Email:    rakib@example.com
  Password: password

  (Change all passwords immediately after first login!)


━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
TROUBLESHOOTING
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

❌ "500 Server Error"
→ Check storage/ permissions: chmod -R 775 storage/
→ Check .env file exists and APP_KEY is set
→ Set APP_DEBUG=true temporarily to see errors
→ Check /storage/logs/laravel.log

❌ "Class not found"
→ Run: composer dump-autoload
→ Run: php artisan optimize:clear

❌ "No application encryption key"
→ Run: php artisan key:generate

❌ "Database connection refused"
→ Verify DB_HOST=localhost (not 127.0.0.1 on some hosts)
→ Check DB_DATABASE, DB_USERNAME, DB_PASSWORD in .env
→ Test connection in phpMyAdmin first

❌ "Writable permissions" warning
→ chmod -R 777 storage/ bootstrap/cache/  (development only)
→ For production: 755 with www-data ownership

❌ PDF not generating
→ Ensure barryvdh/laravel-dompdf is in vendor/
→ Run: composer require barryvdh/laravel-dompdf

❌ Images not showing
→ Run: php artisan storage:link
→ Ensure public/storage symlink exists

❌ Login loops / redirect issues
→ Clear: php artisan cache:clear
→ Check SESSION_DRIVER=file and storage/framework/sessions/ is writable


━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
PACKAGE LIST (composer.json key dependencies)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

{
  "require": {
    "php": "^8.2",
    "laravel/framework": "^11.0",
    "laravel/breeze": "^2.0",
    "barryvdh/laravel-dompdf": "^3.0",
    "laravel/sanctum": "^4.0"
  },
  "require-dev": {
    "fakerphp/faker": "^1.23",
    "laravel/pint": "^1.13",
    "phpunit/phpunit": "^11.0"
  }
}

Install DomPDF separately if needed:
  composer require barryvdh/laravel-dompdf

Publish DomPDF config:
  php artisan vendor:publish --provider="Barryvdh\DomPDF\ServiceProvider"


━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
BOOTSTRAP/APP.PHP — MIDDLEWARE REGISTRATION
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

In bootstrap/app.php, register middleware aliases:

```php
->withMiddleware(function (Middleware $middleware) {
    $middleware->alias([
        'admin'  => \App\Http\Middleware\EnsureUserIsAdmin::class,
        'tenant' => \App\Http\Middleware\EnsureUserIsTenant::class,
    ]);

    // Redirect after login by role
    $middleware->redirectGuestsTo('/login');
})
```

In app/Http/Controllers/Auth/AuthenticatedSessionController.php
(or in AppServiceProvider boot):
```php
// After login, redirect by role
if (Auth::user()->isAdmin()) {
    return redirect()->route('admin.dashboard');
} else {
    return redirect()->route('tenant.dashboard');
}
```


━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
QUICK REFERENCE — ARTISAN COMMANDS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

php artisan bills:generate               # Current month
php artisan bills:generate --month=2025-07  # Specific month
php artisan bills:mark-overdue           # Mark past-due bills
php artisan migrate                      # Run new migrations
php artisan migrate:fresh --seed         # ⚠️ RESETS DB + re-seeds
php artisan optimize:clear               # Clear all caches
php artisan config:cache                 # Cache config (prod)
php artisan route:cache                  # Cache routes (prod)
php artisan storage:link                 # Create storage symlink
php artisan queue:work                   # If using queues


━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
DEFAULT ADMIN CREDENTIALS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  URL:      https://flats.yourdomain.com/admin/dashboard
  Email:    admin@shakilshomes.com
  Password: password

  ⚠️ CHANGE THESE IMMEDIATELY AFTER FIRST LOGIN!

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Shakil's Homes FMS v1.0 — Built with Laravel 11
Support: Check Laravel docs at https://laravel.com/docs/11.x
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━