# Getting Started

Welcome to VeloFrame, a minimalist PHP framework for rapid, scalable web development. This guide will walk you through setup, project structure, and your first steps.

---

## Prerequisites
- **PHP 7 or higher**
- **Apache** (with mod-rewrite) or any web server that supports URL rewriting

---

## 1. Installation
### Clone the Repository
Open your terminal and run:
```bash
git clone https://github.com/URW-CE-IT/veloframe.git
```

### Project Structure Overview
After cloning, your project will look like:
```
pages/                 # Your page controllers (PHP)
templates/             # HTML templates
templates/components/  # Reusable HTML components
VeloFrame/             # Core framework code
index.php              # Main entry point
.htaccess              # URL rewriting rules
```

---

## 2. Configure URL Rewriting
To enable clean URLs, use this `.htaccess` in your project root:
```apache
RewriteEngine On
RewriteBase /
RewriteRule ^(img|css|js)/(.*)$ - [L]
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule ^(.*)$ index.php?rpath=$1 [QSA,L]
```
- **Tip:** Adjust `RewriteBase` if your project is in a subfolder.

---

## 3. Running the Development Server
For quick local testing, use PHP’s built-in server:
```bash
php -S localhost:8000 index.php
```
- Visit [http://localhost:8000](http://localhost:8000) in your browser.
- For production or full URL rewriting, use Apache or a compatible server.

---

## 4. Your First Page
1. **Create a new file** in `pages/`, e.g. `HelloHandler.php`:
   ```php
   # @route /hello
   class HelloHandler extends DefaultPageController {
       public function handle() {
           $tpl = new VeloFrame\Template("index");
           $tpl->setVariable("title", "Hello World!");
           return $tpl->output();
       }
   }
   ```
2. **Add a link** to `/hello` in your template or visit `/hello` in your browser.

---

## 5. Next Steps
- [Templates & Components](./Templates.md): Learn to build dynamic UIs.
- [Configuration](./Configuration.md): Tune your project settings.
- [Architecture](./Architecture.md): Understand the framework flow.
- [Routing](./Routing.md): Map URLs to controllers.

---

## Troubleshooting
- **Blank page?** Check file permissions and error logs.
- **404 errors?** Ensure `.htaccess` is present and URL rewriting is enabled.
- **Need help?** See the [FAQ](./FAQ.md) or open an issue on GitHub.

Happy coding with VeloFrame! 🚴‍♂️