framex/framexEngine-pro

Fork 0

Files

webclubz 3a6ab777c9 Firts up

2026-05-13 21:17:36 +03:00

10 KiB

Raw Permalink Blame History

Framex Engine

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

What is Framex?
Features
Quick Start
Project Structure
Creating Pages
- PHP Pages
- Markdown 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: 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:

<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

10 KiB Raw Permalink Blame History