README

A lightweight, theme-driven PHP framework for building websites powered by ReadyCMS.

This framework is currently project-oriented: you clone it into a new site and adjust configuration, templates, and (optionally) controllers. Over time, parts of the framework (including the ReadyCMS API SDK and base themes) will become reusable Composer packages.

Key Concepts

Theme system (overrides + parent + shared)

Themes are resolved using a predictable fallback chain:

THEME (project overrides)
_THEME_PARENT (base/upgradable theme package)
_shared (always-present shared fallback)

This allows teams to update a base theme without overwriting project customizations.

Folder conventions

Under app/themes/:

_shared/ → shared templates/includes used by all themes (must exist)
_<name>/ → base theme package (upgradable, reusable)
<name>/ → project/site overrides (safe to edit)

Public assets follow the same pattern under public/:

public/_shared/ (optional)
public/_<name>/
public/<name>/

Example

Using project overrides diline with base theme package _vidaa:

app/themes/
  _shared/
  _vidaa/
  diline/

public/
  _vidaa/
  diline/

Config:

define('THEME', 'diline');        // overrides: app/themes/diline
define('THEME_PARENT', 'vidaa');  // base: app/themes/_vidaa

Requirements

PHP 8.1+ (recommended)
Web server (Apache/Nginx) or local stack (Laragon/XAMPP)
Composer (for vendor dependencies)

Getting Started

1) Clone the project

git clone <repo-url> my-site
cd my-site

2) Install dependencies

composer install

3) Configure environment

Copy sample files and adjust values:

app/config/config.sample.php → app/config/config.php (or your actual config path)
.env.sample → .env (if used)

Make sure you set:

DB credentials (if applicable)
domain / base URL values
caching configuration (if applicable)

4) Configure theme

In your config:

define('THEME', 'diline');
define('THEME_PARENT', 'vidaa');

5) Ensure writable directories

Make sure these are writable by PHP:

app/templates_c/ (Smarty compile)
storage/ (if used)
logs/ (if used)
cache/ (if used)

6) Run locally

Point your local vhost to the project public/ directory.

Template, Include & Asset Resolution

The theme chain applies consistently to:

Smarty templates (templates/)
Theme-root template includes (includes/*.html)
PHP includes via requireTemplateDirectoryFile()
Public assets via getPublicAssetUrl() / asset_url

Smarty includes

If a template contains:

{include file="includes/head.html"}

Smarty will resolve it using:

app/themes/{THEME}/includes/head.html
app/themes/_{THEME_PARENT}/includes/head.html
app/themes/_shared/includes/head.html

Routing Controllers from Themes

Some routes/controllers may be loaded from theme folders using rawFileRoute(). Resolution order is the same theme chain:

app/themes/{THEME}/...
app/themes/_{THEME_PARENT}/...
app/themes/_shared/...

Updating

This repo is currently updated via Git (pull/merge from upstream).
Base theme updates are done by updating the parent theme folder (e.g. _vidaa) while keeping project changes in the override theme (e.g. diline).

Future plan:

ReadyCMS API SDK via Composer
Framework and base themes distributable via Composer

Project Structure (high level)

core/ → framework core
app/ → project-level code (templates, configs, controllers, themes)
app/themes/ → themes (THEME, _THEME_PARENT, _shared)
public/ → public entry + theme assets
libs/vendor/ → Composer dependencies (if stored here in this project layout)

License

MIT

readycms / readycms-php-framework

Maintainers

Package info

Statistics

Security