Files and Resources and Hypertext
A Content Management System

Welcome! This is the homepage of Farah , a PHP-based CMS.

This website is going to have all the info you need to use it, like an API documentation and code examples probably.

FAQ

What is Farah ?

Farah stands for "Files and Resources and Hypertext".

It's used on here to invariably mean one of the following:

Okay, but what does it do?

It serves content! Like websites.

Basically, you define a sitemap and link each page to one of your assets, and with those definitions Farah resolves requests to your server by handing out the assets.

So... how do I define a sitemap?

You create an XML according to the sitemap spec .

What about assets?

An "asset" in the Farah context is an identifiable resource of your domain. It can be a file, the result of an XSL transformation, or something generated by your PHP code.

Assets are defined in something called a module manifest, which is an XML file according to the module manifest spec .

Okay, I've defined some assets. How do I reference them?

Every asset gets assigned a Farah URL based on the module it's defined in, and its position in the manifest file.

Farah URLs can be used just like file paths, e.g., fopen , DOMDocument::load , xsl:import , etc. all work.

What's the syntax of a Farah URL?

A basic URI, with some additional rules:

  • The scheme must be "farah".
  • The user is required, and identifies the vendor.
  • The password is forbidden.
  • The host is required, and identifies the module.
  • The port is forbidden.
  • The path is optional, and identifies the asset inside the module manifest.
  • Arguments are optional, and identify input parameters for the asset.
  • The fragment is optional, and identifies a specific type representation of the asset.
farah-url = "farah://" vendor "@" module path? ("?" arguments)? ("#" type)?

vendor = \w+

module = \w+

path = (/\w)+

arguments = .+

type = \w+

For example, farah://slothsoft@farah/request#xml identifies the "xml" representation of the asset with the name "request" in the module "farah" by vendor "slothsoft".

What's this about representations?

Assets may define multiple representations of themselves, so that they can be used transparently in contexts where a specific type of data is expected.

For example, all native Farah asset types have an "xml" representation, so that they can be used as-is in XSL transformations.
That means if farah://foo@bar/my-csv-file points to an sfm:resource asset of type text/csv, you can get an XML document of those comma-separated values by accessing farah://foo@bar/my-csv-file#xml.

Wait, is that it? I was promised an API documentation!

Uhm. Yeah. Sorry! D: I'll get around to that eventually.

For now, the best I can offer is the source code to this website, as it's a nigh-barebone Farah installation, and thus could serve as starting point for a new one: https://github.com/Faulo/server-farah.slothsoft.net