10 KiB
Framex Engine
A lightweight, high-performance PHP engine for building static sites and modern web applications.
Table of Contents
- What is Framex?
- Features
- Quick Start
- Project Structure
- Creating Pages
- Templates & Partials
- Styling
- Helper Functions
- Contributing
- 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
# 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:
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
$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, and wraps it in your template.
# 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
$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 partial('topmenu'); ?>
Create your own:
touch templates/partials/newsletter.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 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
# Watch for changes and rebuild automatically
npm run dev
Production
# 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: darkon 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:
<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
$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
// 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:
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.
- Fork the repository
- Create your feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
License
Framex Engine is open-source software licensed under the MIT License.
Built with ❤️ by Prodigital Framex