"Fossies" - the Fresh Open Source Software Archive

Member "serendipity/docs/ARCHITECTURE.md" (20 Nov 2022, 4393 Bytes) of package /linux/www/serendipity-2.4.0.zip:

As a special service "Fossies" has tried to format the requested source page into HTML format (assuming markdown format). Alternatively you can here view or download the uninterpreted source code file. A member file download can also be achieved by clicking within a package contents listing on the according byte size field.

A hint: This file contains one or more very long lines, so maybe it is better readable using the pure text view mode that shows the contents as wrapped lines within the browser window.

The relevant architecture of serendipity (s9y) depends on the entry point. A regular visitor of a blog will be served by the index.php, which chains file after file via include together to decide which page to render. The backend is served by serendipity_admin.php, while the feeds come from rss.php, and comment.php is where comments, trackbacks and pingbacks are received.

Main structure

All of these entry points work with the general file structure of the software. include/ contains the thematically grouped functions that other code can call. include/admin/ is where the main code for backend pages live, the code there does the work related to the request and at the end decides which page to render. The HTML generation for frontend and backend is done via smarty template files located under templates/, with 2k11 being the default theme used. The files under templates/2k11/admin/ will generate the backend (if the chosen theme does not come with a custom admin backend), the files in the folder above the frontend pages regular visitors see.

Program flow, overview

When a request is served by the index.php, broadly this happens: The index.php will use regular expressions (partly configurable by the user) to decide which routing function has to react. Most of those call include/genpage.inc.php and set some parameters in the $serendipity global. genpage.inc.php decides based on $serendipity['GET']['action'] what to do, and either prints a specific blog entry or multiple or e.g. the search page with search results. serendipity_printEntries is the main function to print articles given to it, it will call the smarty templates defined under the currently used theme (fallback if a file is missing: 2k11), and serendipity_fetchEntries is the main function that gets entries from the database.

A request served by serendipity_admin.php, after the login status check, is treated depending on $serendipity['GET']['adminModule']. The value is mapped to the files in include/admin, which are then included. Those look at $serendipity['GET']['adminAction'], do the work and call the .tpl files under 2k11/admin/ to generate the HTML. The backend Javscript is generated by the serendipity_editor.js.tpl.

Throughout all flows, the global $serendipity is filled with information. It holds a lot of the needed information about the current state, blog configuration and the request parameters. It is also read a lot and can thus be used to transmit information to later sections of the program flow. Please use this sparingly in new code.

Plugin System

The plugin system is rather powerful. Calls to serendipity_plugin_api::hook_event('event_name', $eventData, $addData) are sprinkled throughout the whole code. That function then iterates through all event plugins under plugins/, so those plugins that have registered the called event can run their PHP code. For example, anti-spam plugins will be given submitted comments, do their work and then signal via the plugin layer and the $serendipity global whether the plugin should be saved and shown, saved and moderated or completely denied. And plugins cann add to the javascript and css served in the frontend via the js and css plugin events.

Sidebar plugins instead are called whenever a page with a sidebar in the frontend is generated. They can not register multiple events. They can only emit HTML via their generate_content function.

Database Layer

Serendipity supports multiple database engines, the main ones being MySQL, SQLite and PostgreSQL. Serendipity will include include/db/db.inc.php, that file will then include include/db/{$serendipity['dbType']}.inc.php. $serendipity['dbType'] is set in serendipity_config_local.inc.php, a file generated during installation.

Always when s9y has to talk to the database it will do so via the function serendipity_db_query or serendipity_db_schema_import, functions defined in the included database layer file and adapted for their respective database engine. serendipity_db_schema_import can replace parts of the SQL query with specific expressions for their database layer. It will for example replace {BOOLEAN} to something that works in all supported database engines (SQLite for example has no boolean database type, PostgreSQL does).