HisarBlok · documentation

Modules

Blog, forum, forms, members: every large piece of HisarBlok is a module, switched on or off per site. Core's own modules use exactly the same interface as one you would write.

All docs

For version 0.13.1.

The modules in the box

Module	What it does	On by default
`pages`	Pages written in Markdown or built from blocks	yes
`blocks`	The standard block types pages are built from	yes
`media`	Image library: re-encoding, metadata removal, resizing, WebP	yes
`redirects`	Keeps old addresses alive; exports real 301 rules	yes
`announcements`	Short announcements on the home page	yes
`blog`	Dated posts, tags, a paged index, feeds	no
`menu`	Editing the site menu from the admin	no
`search`	A static index searched in the browser	no
`forms`	Contact and sign-up forms as blocks	no
`comments`	Comments under pages and posts, approved first	no
`forum`	Categories, topics, replies; static pages	no
`members`	Visitor accounts with a verified email	no
`downloads`	Products, releases, files, counted links, checksums	no

Switching on and off

Every module is switched on or off per site on the admin's Modules screen. A module that is off is not loaded, registers no hooks and serves nothing; the files it wrote to the site are removed. Its data stays: switching it back on picks up where it left off. The site root, a language's root, the uploaded media, the theme's files and another module's area are never removed along the way.

Roles: replacing a module

forum, members and downloads are roles. Only one module may hold a role on a site: switching on a module of your own that provides the same role switches off the one that held it. So two download managers never publish over each other, and a site can replace one of our modules with its own.

A module of your own

A module is a folder in modules/ with a module.json manifest:

modules/mything/
  module.json            manifest (required)
  src/module.php         loaded only while the module is on for the site
  migrations/001-x.sql   applied once each, in order
  migrations/001-x.mysql.sql   the same schema for MySQL/MariaDB
  themes/block-x.php     templates for the module's blocks; any theme can override them by name
  lang/tr.json           translations of the module's own strings

The manifest says which tables and paths the module touches, which files it produces, which modules it needs and which role it provides. hisarblok make:module <name> writes a working skeleton of all of it: the manifest, a panel screen with a form and a delete that asks first, one table in both SQL dialects, a hook, a Turkish table and its own test.

What a module can do:

add an admin screen and a menu group (every screen declares a capability; role names are never tested),
add a page block,
write pages and files (honouring the site's ownership rules),
take a form from visitors: only through go.php, behind the shared protections,
give visitors a counted link: through get.php,
take part in core's behaviour through hooks, and write to the audit log.

Rules that keep a site safe

Everything a visitor sends is untrusted: escape it with h(), turn text into HTML only with markdown(), and build links with the helper that refuses javascript: and data: addresses.
Admin forms carry a CSRF token and the handler checks it first.
Work only on the site being worked on, and check in the query that an id from the request belongs to it. An account may be limited to some sites.
A visitor endpoint has no session: use the rate limits, recognise a visitor by a salted digest rather than the address, and store totals rather than logs where you can.
Files written into a document root are served as they are: accept nothing a web server would execute.