PumaCMS

Having an understanding of the Puma domain models will make it much easier to write your own plugins. Not that Puma is a particurly difficult to understand application, or that CMSs in general have obscure domain models, but just that every one is so different you’re not likely to want to waste your time translating SQL into understanding.In case you’ve forgotten your UML, here’s a brief reminder of UML syntax:

• Class names go on the top line of the box (like Page, User, etc).
• Abstract class names are written in italics and represent classes that shouldn’t be directly instantiated.
• Attributes go in the middle of the box (date, time, etc). The name comes first, then the type.
• Methods go in the bottom box (authorized, etc).
• Static methods are underlined and don’t need to be called on an instance.
• Types followed by types in angle brackets (List) are generics. List means “A list whose elements are of type Page”.

That’s the brief rundown. You don’t need to be a UML expert to see what’s going on up there.

Gross anatomy

A Puma website is a single tree of Page objects and a set of Users. The pages are versioned; each page has at least one Version object associated with it that contains the contents of the page for a particular version of the page. Each User has a permission level which is compared with a given page’s permissions to determine whether that user can edit or view the page. There’s a special user that corresponds to an anonymous user of the website; it’s named Anonymous appropriately enough.

Most pages in a Puma website are HtmlPages, whose versions contain raw HTML. Other subtypes of Page are useful for other purposes—HiddenPages, for example, shouldn’t be listed on any public-facing portion of the website, so you can hide administrative pages like Copyright beneath a HiddenPage.

This article provides a gross overview of the Puma request handling timeline, which is useful if you’re poking around in the Puma internals trying to debug or add something.

1. Initialization. The first order of business is to make the PHP environment sane and load preferences. This takes place in init.inc. Puma runs with all error reporting turned on, and it’s a matter of development policy that all warnings be fixed. We immediately fix any magic quoting that PHP may have inflicted on the request variables to avoid quoting and unquoting headaches later. Puma installs PEAR error handlers so no PEAR functions fail silently.
   With the PHP environment set up for early error reporting, execution continues.
2. Loading and initializing components. Next, the dispatcher is loaded, along with Smarty, and any files that reside in the model/ directory. That means if you add a new model, you don’t need to explicitly require it. A new Smarty object and Dispatcher object are created, but no request processing is done.
3. Populate the dispatch table. Puma’s dispatcher is responsible for mapping requests into actions, which happens by matching PATH_INFO with the dispatcher’s table of registered controllers and their handlers. Puma’s dispatch table is created automatically by the dispatcher when it autoloads the controller classes in the controller/ directory. If you create a new controller and place it in the controller/ directory, the dispatcher will find it and register its handlers without any special action on your part. See the articles on the dispatcher for more information.
4. Dispatch the request. Puma calls the dispatcher with PATH_INFO. The dispatcher determines which handler to run. The handler performs whatever action is necessary. The dispatcher stashes any information which may be useful in rendering the resulting View in the global Smarty object. If the browser needs to be redirected (for example, after a login step, or after submitting a page edit), the handler accomplishes this by calling the redirect method of the dispatcher object. Unless the handler redirects or aborts abnormally, control eventually returns from the dispatch process. Puma determines which template to render by looking in the Smarty variable stash for a variable called “template” which should have been set by the handler. Typically, if the request was for /page/view/231, the handler PageController:view() will set this variable to “page.view”. Puma looks for a GET variable called “format,” which it appends to the template name if it’s found—for example, /page/view/231?format=xml results in a final template name of “page.view.xml” while /page/view/231 results in a final template name of “page.view.html”. Otherwise, Puma assumes the format is HTML. Puma hands off to Smarty to render the template.
5. Augmented Smarty template search paths. Puma uses an extended Smarty (aptly called MySmarty) which looks in multiple locations for a template before giving up. This way, you can override the ugly Puma default templates on an as-needed basis simply by putting your templates in the site/template directory. MySmarty always prefers your templates to the default Puma templates, so you don’t have to do anything special to tell Puma you’ve overridden a template.

That’s it! Once Smarty renders the output, the rest is history.