# Simba MVC – Quick Start Guide

Welcome to Simba, a lightweight PHP MVC starter. Follow the steps below to get a fresh install running, configure your environment, and understand the essentials for day-to-day work.

## 1. Prerequisites
- PHP 8.1 or newer with PDO and cURL extensions enabled.
- Composer (optional; only needed if you plan to pull in additional dependencies).
- MySQL 8.x (optional; required only when you want the database features).
- Redis server (optional; used if you enable the cache helpers).

## 2. Install Simba
1. Clone or copy the project into your web server’s document root.  
   Example: `git clone <repo-url> /var/www/simba`
2. Ensure your virtual host (Apache or Nginx) points to the project root (the directory that contains `index.php`).
3. Copy `.env.example` to `.env` if you prefer to edit the file manually before using the wizard.
4. Make the CLI helper executable if you plan to use it: `chmod +x bin/simba`.

## 3. Run the Onboarding Wizard
Simba ships with an `Onboard` controller that jump-starts configuration:

1. Visit `http://<your-host>/onboard` in your browser.
2. Review the pre-filled values. Update any fields that need to change (database details, Redis, etc.).
3. Click **Save .env**. Simba will generate a secure `APP_KEY` if you leave it blank and write everything to the root `.env` file.
4. Refresh the page if you want to adjust anything; saving again will overwrite the values with your latest input.
5. After confirming the app loads correctly, delete the onboarding helper for security:
   - Remove `app/controllers/OnboardController.php`
   - Remove the `app/views/onboard/` directory
6. Set **Debug Mode** to `false` before you roll into production to hide verbose PHP errors.

> Tip: Never commit `.env` to your repository. Store secrets in a secure vault or environment variables instead.

## 4. Explore the Structure
- `app/controllers` – Controllers extend `app/core/Controller.php`. Add new controllers here (e.g., `php` class `PostsController` with methods `index`, `show`, etc.).
- `app/views` – Blade-free PHP templates. Match controller actions with view files (e.g., `PostsController@index` → `app/views/posts/index.php`).
- `app/models` – Plain PHP models. Use `app/core/Database.php` for PDO access.
- `app/config` – Framework configuration. `config.php` pulls values from `.env`.
- `app/helpers` – Global helpers available across controllers and views.
- `bin/simba` – CLI helper for migrations and version info.

## 5. Common Tasks
- **Add a route**: Access routes via `/controller/action/param`. Example: `/posts/show/42`.
- **Use migrations**:
  1. Drop SQL files into `app/migrations` (e.g., `20240101_create_users.sql`).
  2. Run `php bin/simba migrate` or visit `/migration/run`.
- **Access database**:
  ```php
  $db = Database::getInstance();
  $rows = $db->query('SELECT * FROM users')->fetchAll();
  ```
- **Render a view**:
  ```php
  class PostsController extends Controller {
      public function index() {
          $posts = []; // fetch or mock
          $this->view('posts/index', ['posts' => $posts]);
      }
  }
  ```

## 6. Deployment Checklist
- Copy the project to your server (or deploy via CI).
- Set production-ready values in `.env` (app URL, database credentials, Redis).
- Flip `DEBUG_MODE=false` so errors are logged but not displayed publicly.
- Ensure `APP_KEY` is unique per environment.
- Run migrations (`bin/simba migrate`).
- Harden the install:
  - Delete any leftover onboarding files if you forgot earlier.
  - Disable display of PHP errors in production (`display_errors=0`).
  - Ensure the `public/` directory (if you use it) has correct permissions for uploads.
- Run `php scripts/smoke.php https://your-domain/` to confirm key routes respond as expected.

## 7. What’s Next?
- Use the `TODO.md` file to track follow-up work.
- Review `README.md` for more background and packaging instructions.
- Extend the framework with your own helpers, middleware, or service providers as needed.

Happy building! If you run into trouble, revisit the onboarding wizard or inspect the controller/view examples shipped with the framework.