Guide

The framework is opinionated on purpose. It gives every module the same directory layout, the same way of declaring its database tables, the same way of reading its configuration, and the same way of talking to other modules. Once you learn that shape once, you can open any module in any site and know exactly where everything is. This guide teaches that shape and the reasoning behind it.

What you build with it

A site made with the framework is a single PHP application served by Apache. From the same set of modules you build:

• public, server-rendered web pages with their own URLs and routes,
• a member area with registration, login and per-member data,
• an admin system for managing that data,
• a JSON Api for other clients to call,
• background work handled by queues and scheduled cron tasks.

Everything runs from one entry point, and every feature arrives as a module you include and configure.

Everything is a module

A module owns one concern and everything that concern needs: its database tables and migrations, its data objects, its pages and routing, and its configuration. The Member module owns members and their authentication. The MemberFolder module owns a folder tree. Your own Shop module would own products and orders.

Modules come from two places. Shared modules live in a common folder and are reused across many sites, including the framework's own modules. Site-specific modules live inside the site that uses them. A site is the set of modules it includes, plus the small amount of glue that starts them up.

The shape of a site

A site is a web root with a single entry point, a configuration file kept above the web root, and the modules the site is built from, with the shared framework modules mounted alongside. That layout is fixed: the folders a site holds, and the folders a module holds, are the same every time, so you always know where to look.

The Site structure page lays out the site folder in full, and Module layout does the same for a single module. Running locally shows the Docker setup that mounts the framework and the site together.

Modules stay loosely coupled

Modules are independent. A module includes exactly the other modules it uses, at the top of its index file, and it configures another module by calling that module's own configuration functions. There is no global service container and no hidden autowiring: a module's dependencies are the list of includes you can read at the top of the file.

When one module needs to plug into another, it does so through a small, declared surface. The folder module, for example, lets an application register a folder type by calling its config function:

MemberFolderConfig::Type('Shop', 'Product', function() {
    MemberFolderTypeConfig::Content(
        'Shop', 'Product',
        'ShopProductFolder::Count',   // how many products are in a folder
        'ShopProductFolder::Render'   // how to draw them
    );
});

The shop module knows about the folder module, and the folder module knows nothing about shops. That one-way relationship is what keeps modules reusable. The Loose coupling page covers this pattern in full.

Opinionated by design

The framework asks you to lay things out exactly as it expects. That consistency is the point: it is what lets code stay readable as a site grows. A few of the conventions you will meet in this guide:

• every module has the same directory layout and the same kind of index file,
• database tables are created and changed through numbered migration scripts,
• data travels in plain data objects that hold fields and nothing else,
• input is checked as it enters a function, so the rest of the code can trust it,
• a variable is assigned once, which keeps each value easy to follow.

You will learn each of these in place, with the reasoning attached, so the rules feel like a single coherent way of working rather than a list to memorise.

Explore the guide

Read it in order the first time. Each section builds on the one before, and the early pages give you a running site to try the later ideas against. Once you know your way around, use the cards below or the side menu to jump straight to a topic.

Next: Design philosophy.