You've already forked framexEngine-pro
Firts up
This commit is contained in:
384
README.md
384
README.md
@@ -1,2 +1,384 @@
|
||||
# framexEngine-pro
|
||||
# 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>
|
||||
|
||||
Reference in New Issue
Block a user