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:
- The CMS, duh.
- Its composer package, slothsoft/farah .
- Its github repository, https://github.com/Faulo/slothsoft-farah .
-
Its PHP streaming protocol,
farah://
. -
Its root module,
farah://slothsoft@farah
.
- 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 iffarah://foo@bar/my-csv-file
points to ansfm:resource
asset of typetext/csv
, you can get an XML document of those comma-separated values by accessingfarah://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