# Framex Engine

> A lightweight, high-performance PHP engine for building static sites and modern web applications.

[![PHP](https://img.shields.io/badge/PHP-8.0%2B-777BB4?logo=php&logoColor=white)](https://php.net)
[![Tailwind CSS](https://img.shields.io/badge/Tailwind_CSS-v4-06B6D4?logo=tailwindcss&logoColor=white)](https://tailwindcss.com)
[![License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)

---

## Table of Contents

- [What is Framex?](#what-is-framex)
- [Features](#features)
- [Quick Start](#quick-start)
- [Project Structure](#project-structure)
- [Creating Pages](#creating-pages)
  - [PHP Pages](#php-pages)
  - [Markdown Pages](#markdown-pages)
- [Templates & Partials](#templates--partials)
- [Styling](#styling)
- [Helper Functions](#helper-functions)
- [Contributing](#contributing)
- [License](#license)

---

## What is Framex?

**Framex Engine** is a minimal PHP framework designed for developers who want to ship fast static sites without the bloat of traditional CMS platforms or over-engineered frameworks.

No database. No complex routing files. No plugin ecosystem to maintain. Just **PHP files**, **Markdown content**, and a directory structure that mirrors your URLs.

Framex is perfect for:

- Landing pages & marketing sites
- Documentation & blogs
- Portfolios & personal sites
- Prototypes & MVPs
- Any site where content changes faster than architecture

---

## Features

| Feature | Description |
|---------|-------------|
| **URL-Driven Routing** | Your folder structure *is* your routing. Zero configuration. |
| **Infinite Pages** | Create a file → get a page. No database required. |
| **Markdown Support** | Write content in `.md` files. Rendered automatically via Parsedown. |
| **Template System** | Switch layouts per page. Reusable partials for DRY templates. |
| **Tailwind CSS v4** | Pre-configured with Lightning CSS. Utility-first, blazing fast builds. |
| **Asset Pipeline** | Built-in cache busting, file hashing, and development helpers. |
| **Zero Dependencies** | Works on any shared host. No Composer required for core features. |
| **Dark Theme Ready** | Modern dark UI components included out of the box. |
| **Light / Dark Mode** | Automatic system detection with manual toggle. Persisted in localStorage. |

---

## Quick Start

### Requirements

- PHP 8.0 or higher
- Node.js 18+ (for CSS build pipeline)

### Installation

```bash
# Clone the repository
git clone https://github.com/yourusername/framex-engine.git my-project
cd my-project

# Install dependencies
npm install

# Start the development watcher
npm run dev
```

Point your web server to the `public/` directory and visit `http://localhost`.

> **Note:** If you use PHP's built-in server, run it from the project root:
> ```bash
> php -S localhost:8000 -t public/
> ```

---

## Project Structure

```
framexEngine-Base/
├── app/
│   ├── views/              # Your pages live here
│   │   ├── index.php
│   │   ├── about.php
│   │   └── blog/
│   │       └── hello-world.md
│   └── about/
│
├── core/
│   ├── classes/
│   │   ├── Engine.php      # Router & request handler
│   │   ├── Framex.php      # View renderer
│   │   └── Parsedown.php   # Markdown parser
│   ├── config.php          # Constants & configuration
│   ├── functions.php       # Global helper functions
│   └── ignition.php        # Application bootstrap
│
├── templates/
│   ├── main.php            # Default layout (nav + footer)
│   ├── clean.php           # Minimal layout
│   ├── admin.php           # Dashboard layout
│   ├── error404.php        # 404 error page
│   └── partials/
│       ├── topmenu.php
│       └── footer.php
│
├── public/
│   ├── css/                # Compiled stylesheets
│   ├── js/                 # Scripts
│   ├── images/
│   └── index.php           # Entry point
│
├── public/css/src/         # CSS source files
│   ├── style.css           # Main site styles
│   ├── admin.css           # Admin panel styles
│   └── ...
│
└── package.json            # Build scripts & dependencies
```

---

## Creating Pages

### PHP Pages

Create a file in `app/views/` and it instantly becomes a URL:

| File | URL |
|------|-----|
| `app/views/index.php` | `/` |
| `app/views/about.php` | `/about` |
| `app/views/blog/post.php` | `/blog/post` |
| `app/views/contact/index.php` | `/contact` |

Example page (`app/views/about.php`):

```php
<?php
$data['title'] = "About Us";
?>

<h1>About Framex</h1>
<p>This page was created by dropping a single PHP file in the views folder.</p>
```

### Markdown Pages

Prefer writing in Markdown? Save your content as a `.md` file:

| File | URL |
|------|-----|
| `app/views/changelog.md` | `/changelog` |
| `app/views/docs/installation.md` | `/docs/installation` |

Framex automatically detects the extension, runs it through [Parsedown](https://parsedown.org/), and wraps it in your template.

```markdown
# Installation

1. Clone the repo
2. Run `npm install`
3. Start hacking
```

---

## Templates & Partials

### Switching Templates

By default, every page wraps inside `templates/main.php`. You can switch this per page:

```php
<?php
$data['title']     = "Admin Dashboard";
$data['template']  = "admin";  // Uses templates/admin.php
?>
```

Built-in templates:

| Template | Purpose |
|----------|---------|
| `main` | Default layout with navigation and footer |
| `clean` | Minimal layout, no wrappers |
| `admin` | Dashboard sidebar layout |

### Partials

Reusable chunks live in `templates/partials/`:

```php
<?php partial('topmenu'); ?>
```

Create your own:

```bash
touch templates/partials/newsletter.php
```

```php
<!-- templates/partials/newsletter.php -->
<form action="/subscribe" method="post">
    <input type="email" name="email" placeholder="Enter your email">
    <button type="submit">Subscribe</button>
</form>
```

Include it anywhere:

```php
<?php partial('newsletter'); ?>
```

---

## Styling

Framex ships with **Tailwind CSS v4** pre-configured. The build pipeline uses the Tailwind CLI with Lightning CSS for maximum performance.

### Development

```bash
# Watch for changes and rebuild automatically
npm run dev
```

### Production

```bash
# Build minified CSS for production
npm run build
```

### CSS Source Files

| File | Output | Purpose |
|------|--------|---------|
| `public/css/src/style.css` | `public/css/style.css` | Main site styles |
| `public/css/src/admin.css` | `public/css/admin.css` | Admin panel styles |
| `public/css/src/responsive.css` | `public/css/responsive.css` | Responsive overrides |
| `public/css/src/vendors.css` | `public/css/vendors.css` | Third-party styles |

### Using Custom CSS

You are not locked into Tailwind. The CSS pipeline is completely optional. You can:

- Write vanilla CSS in `public/css/src/`
- Use Sass/SCSS (still installed)
- Link external CSS frameworks from a CDN
- Replace the entire build pipeline

---

## Light & Dark Mode

Framex includes a built-in light/dark mode toggle that respects the user's system preference and persists their choice in `localStorage`.

- **Automatic detection** — Checks `prefers-color-scheme: dark` on first visit
- **Manual toggle** — Sun/moon button in the navbar
- **Instant switch** — Zero page reload, powered by Tailwind's `dark:` utilities
- **Persistent** — Choice is saved and restored on every page

To style for dark mode in your templates, use Tailwind's `dark:` prefix:

```html
<div class="bg-white text-slate-900 dark:bg-slate-950 dark:text-slate-100">
  <!-- Content that adapts to the current theme -->
</div>
```

---

## SEO & Meta Tags

Every page can define custom meta descriptions and social sharing images through the `$data` array. Framex automatically generates the following tags in the `<head>`:

- `<meta name="description">` — Search engine snippet
- `<meta property="og:*">` — Open Graph (Facebook, LinkedIn, Discord)
- `<meta name="twitter:*">` — Twitter/X Cards

### Setting meta per page

```php
<?php
$data['title']           = "My Awesome Page";
$data['metaDescription'] = "A concise description for search engines and social shares.";
$data['metaImage']       = "/images/og-my-page.png";  // Optional
?>
```

If you do not set a custom description or image, sensible defaults are used automatically.

---

## Helper Functions

Framex includes a set of global helpers to speed up development:

| Function | Usage | Description |
|----------|-------|-------------|
| `asset()` | `asset('css/style.css')` | Versioned asset URLs with cache busting |
| `image()` | `image(800, 600)` | Random placeholder images via Picsum |
| `partial()` | `partial('footer')` | Include reusable template chunks |
| `e()` | `e($userInput)` | Escape HTML entities (XSS protection) |
| `pre()` | `pre($array, true)` | Debug print_r with optional die |
| `summarize()` | `summarize($text, 100)` | Truncate text with ellipsis |
| `urlSlug()` | `urlSlug($title)` | Convert strings to URL-friendly slugs |

### Asset Helper Options

```php
// Basic usage
<link rel="stylesheet" href="<?= asset('css/style.css'); ?>">

// With file hash for cache busting
<script src="<?= asset('js/app.js', ['hash' => true]); ?>"></script>

// With custom prefix
<link rel="stylesheet" href="<?= asset('css/style.css', ['prefix' => 'v']); ?>">

// Absolute URL
<meta property="og:image" content="<?= asset('images/og.png', ['absolute' => true]); ?>">
```

---

## Configuration

Edit `core/config.php` to customize your setup:

```php
define('DEV_MODE', true);           // Toggle development mode
define('SITE_URL', 'https://...');   // Your site URL
define('CSS', '/css/');              // CSS directory
define('JS', '/js/');                // JS directory
```

**Development Mode** (`DEV_MODE = true`):
- CSS URLs append a unique query string on every refresh
- Errors are more verbose

**Production Mode** (`DEV_MODE = false`):
- Assets use file-hash based cache busting
- Cleaner error handling

---

## Contributing

Contributions are welcome! Feel free to open issues or submit pull requests.

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

---

## License

Framex Engine is open-source software licensed under the [MIT License](LICENSE).

---

<p align="center">
  Built with ❤️ by <strong>Prodigital Framex</strong>
</p>