You've already forked framexEngine-pro
385 lines
10 KiB
Markdown
385 lines
10 KiB
Markdown
# Framex Engine
|
|
|
|
> A lightweight, high-performance PHP engine for building static sites and modern web applications.
|
|
|
|
[](https://php.net)
|
|
[](https://tailwindcss.com)
|
|
[](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>
|