mbirth/LuckyCoinkydink
1
0
Fork 0
Code Issues Pull Requests Activity

Add ARCHITECTURE documentation file

Browse Source
This commit is contained in:
onli 2021-02-07 12:04:33 +01:00
parent 674319b36b
commit b546ea3d4c
1 changed files with 25 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

25
docs/ARCHITECTURE Normal file
View File

@ -0,0 +1,25 @@
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).