Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
Fetching latest commit…
Cannot retrieve the latest commit at this time.
|Failed to load latest commit information.|
PlomWiki: extensible PHP wiki with wiki markup and page versioning. Copyright 2010-2012, 2018 Christian Heller / <http://www.plomlompom.de/> License: AGPLv3 or any later version. See file LICENSE for details. INTRODUCTION ============ PlomWiki is a small wiki written in PHP and (by default) using only a file tree of text files as its database. Highly extensible through plugins, its default feature set is small and mostly only includes viewing and single-user editing of wiki pages, a simple wiki markup syntax, histories of page edits and reverting pages to earlier versions. In practice, PlomWiki so far serves as little more than a programming exercise and content management system personally used by me, its author Christian Heller; see website <http://www.plomlompom.de/PlomWiki/> for my real-world use of it. There, I also use a number of plugins, code of which is available at <https://github.com/plomlompom/PlomWikiPlugins>. INSTALLATION ============ Copy the file tree into a web-accessible directory of yours that can run PHP scripts. Access plomwiki.php via your browser; a setup script will run to finalize your installation, creating more files/directories; make sure your filesystem permissions are set liberally. When the script is finished, you should see a default wiki page named "Start" that contains further instructions. Follow them to change your default admin password from "Password" to something more original. USE === In the default configuration, you can view each page's current text by clicking on the "View" link below its title and, if you know the password, edit it by clicking on "Edit". Click on "History" to examine previous changes to the page text and, via the "Revert" links there, revert the page text to earlier versions. Reverting and saving edits to the page needs the admin password. You can set it by clicking on "Set admin password". Per default, only little markup is possible for page formatting, though more can easily be added as plugins (see Technical Details section). For markup syntax explanations, see the markup cheatcodes below the page text editing window. To create a new page, either in your address bar enter the new pagename preceded by "http://[YourDomain/YourPath]/plomwiki.php?title=", or write a link to the new pagename into an existing page's text via the default PlomWiki linking markup (like this: "[[NewPagename]]") and click on it. Notice PlomWiki pagenames are case-sensitive and may only contain the symbols a-z, A-Z, 0-9 and hyphens ("-"). To delete a page, reduce page text to "delete". Empty page text won't be posted. INTRODUCTION TO TECHNICAL DETAILS (see source code comments for details) ================================= Page and history files ---------------------- Wiki pages are stored as text files of their current version in pages/ with the pagename as the filename. In pages/diffs/, edit histories of pages are stored, with single page edits formatted in a diff style defined by the plomwiki.php function PlomDiff(), aiming at resemblance to the output of the Unix diff utility. Page deletion does not actually remove the files but just renames, timestamps and moves page and page history files to pages/deleted/. User actions ------------ The "action=" GET parameter in page URLs determines the user action. Values like "page_view" and "page_edit" correspond to functions like Action_page_view() and Action_page_edit() in plomwiki.php by prepending the value with "Action_" and calling either a function found with that name or defaulting to "Action_page_view". This should give you an idea on how to add new user actions by adding functions like "Action_xyz()". Plugins, markups ---------------- Plugins are implemented as code added by plomwiki.php to its run by examining config/plugins and incorporating the contents of all files referenced therein (and not commented out with a "#") as PHP code. Feel free to add not only functions, but also to extend global variables, especially those acting as hooks in the flow of certain important functions which eval() them as code, like $hook_OutputHTML. Wiki page markup is achieved by running the original page text through page text manipulation functions named and put into order in config/markups. PlomWiki's standard markup is built from functions defined in the plugin plugins/StandardMarkup.php. New markup functions can be made available by incorporating them as plugin code (see above). Database writing ---------------- Writing to PlomWiki's database starts with user input to Action_write(), which generates a list of appropriate DB manipulation tasks and writes them into a todo file in PlomWiki/work. Tasks in this file are worked through independently from the user process that triggered them via WorkTodo(). Tasks written into the todo file work/todo_urgent are worked through and have to be finished before any user action can be performed. Other todo files could be named and separate WorkTodo() calls on them defined as new user actions; such details of Action_write()'s behavior depend on the "t=" GET parameter delivered to it. Functions named "PrepareWrite_$t()" (with $t the "t=" parameter) are called to fill Action_write() with all it needs to know: what to write where, etc. Passwords --------- As single bottleneck for DB writing, Action_write() also is the point where all password checks are called. It delivers POST "password=" and GET "t=" parameters to CheckPW() and waits for its OK. CheckPW() reads from config/passwords a list of keys (could be the names of pages, users, whatever) mapped to password hashes; looks up (plugin-extendable) $permissions to see if the user-provided key is allowed to open targets of type "t=" (i.e. a password for page editing should not be usable for editing users); and if so, compares the hash of "password=" with the appropriate one in the passwords file. CheckPW() will also delay for 10 seconds after a failed authentication attempt any further one from the same IP. HTML output, string files ------------------------- All the strings from which the final HTML output is built are stored in files in config/strings and plugins/strings; plomwiki.php and plugins are to merely contain internal code arranging these files' contents. The first line of these string files defines a separator (usually "§"). A single line containing only the separator separates string entries; each entry starts with a key name, again separated from the string value by the separator. Entries with "#" as key can be used as comments. An empty "#" entry may be used at the end to ensure previous entries don't end with a newline as affixed by many text editors. The key-value pairs from these files are read in via ReadStringsFile() to the global array $s; the separator string is replaced by the string value of $esc ("\r" by default; it can be safely used as it is filtered from all user input by Sanitize()). $s' most important value is $s["design"]: it's used by OutputHTML() as its main template for HTML output. As all string values may, it contains placeholders for other values, identified by the value's key name starting and end by $esc. OutputHTML() recursively calls ReplaceEscapedVars(), which looks up and replaces all these placeholders with their respective $s value. Naming conventions ------------------ Function names, global variables and $s key names provided by plugins are supposed to start with the plugin name, with two exceptions for functions: Here, "PrepareWrite_" and "Action_" may be prepended to the plugin name. As $s["#"] is used for string file comments and repeatedly overwritten, it's unusable for in-code purposes. $s key names starting with "i_" are reserved for values repeatedly generated, used and overwritten in loops.