Web Application Libraries (cs-webapplibs)

NOTICE: this project is under heavy development... so is the page.  :)

This page is meant to be a compliment to the documentation on GitHub: while this gives explanations, the README on GitHub has some actual code examples... of course, downloading the code has tests that probably explain it just as well (if not better).

This package of libraries builds upon the foundation set by the content management framework (cs-content), adding many extra capabilities.  These include:

• Database Access Abstraction Layer (cs_phpdb)
• Authentication Tokens (cs_authToken)
• BBCode Parser (cs_bbCodeParser)
• Generic Data Linker (cs_genercDataLinker)
• Database Storage for Sessions (cs_sessionDB)
• Unified Site Configuration System (cs_siteConfig)
• Tabs System (cs_tabs)
• Generic Database Logging (cs_webdblogger)
• Web Application Upgrade System (cs_webdbupgrade)
• Lock File System (cs_lockfile)

 

Database Access Abstraction (cs_phpDB) [top]

This system allows developers a unified way of accessing multiple database types.  Utilizing this system for all database access allows seemless interaction with the database, regardless of which one is actually being used, allowing for much simpler cross-database programming.

The following databases are supported:

• PostgreSQL
• MySQL (limited transaction support
• SQLite (no transaction support)

 

Authentication Tokens (cs_authToken) [top]

This system allows for very simple implementation of advanced authentication tokens.  Have you ever wanted to implement a "lost password" system, using emails, only to spend hours (or give up on) creating that unique one-time link?  What about implementing an API?  The authentication token system was built for just such a situation.  Using this system, developers can easily make any type of unique key for things like:

• API Access Keys
• Lost Password Links
• Registration Tokens
• Session ID's

The system has the following features:

• SHA-1 Hash (40-character keys)
• checksum for two-phase authentication
• maximum or unlimited uses
• counter indicating total number of uses so far
• expiration date (or unlimited)

Developers can specify a maximum number of uses for an unlimited amount of time, unlimited users for a limited period of time, or any combination.

 

BBCode Parser (cs_bbCodeParser) [top]

Pre-populating forms with data is a hassle, we all know it.  Especially when users start putting in funny characters, or want to have those silly smiley faces, or HTML codes.  Or when trying to display raw code in a helpdesk system.  Or storing emoticons or even HTML code in a messaging system.  By implementing BBCode, your users can specify what is code, or add links, or other things that you might otherwise be all-to-quick to simply strip out.  BBCode not only translates a standard set of codes (tags), but allows developers to programatically add their own tags that have special parsing!

 

Generic Data Linker (cs_genericDataLinker) [top]

A system that... uh... generically links data.  In a database.  Think of it like a way of storing XML in a database using XPath... only not.  And more generic.

Note: this system may be removed in future releases; if you like it, say something.

 

Database Storage for Sessions (cs_sessionDB) [top]

Have you ever been frustrated at all those text files on your server that store user sessions?  Ever thought about deleting all those old, untouched ones?  Or maybe you wanted to easily figure out how many users have been recently active on the site?  Or an easy way of administratively viewing/editing/deleting sessions without having to muck about the filesystem?  Here's your answer!  If you've already implemented CS-Content for templating and session-handling, it's a cinch to enable.

 

Unified Site Configuration System (cs_siteConfig) [top]

If you've been a developer for long, especially with PHP, you've probably seen all kinds of systems on a single server, each with a configuration file that has the same settings.  The same username/password for the database are used in so many different places that changing either would cause nothing less than catastrophe for weeks, many times ending in going back to how it was. 

Using the site configuration system, all the values can be placed into a single XML file.  Duplicated values can be avoided by using template variables, essentially the way that CS-Content uses them.  Configuration items can be automatically placed into the GLOBALS array, set as constants, and even retrieved into an array.

 

Tabs System (cs_tabs) [top]

A system that hooks into CS-Content's templating system for programatically building, styling, and manipulating tabs.  They work just like links, where the link to the current page has an indicator, except with tabs.  It might be a bit complicated to understand at first, but very handy.

 

Generic Database Logging (cs_webdblogger) [top]

Log activities to your database so you always know what is going on!  Many home-grown systems have something similar with cryptic numbers and details (many times with nothing but details), requiring some digging into the database to figure out what it means; many times, the event (that cryptic number) changes so that it no longer matches the actual event.  Or things change, and some events are added, but they use the wrong numbers.

This system uses words to indicate a category and class, along with details, to help quickly find specific types of events: errors, registrations, page views, etc.  Incredibly simple to use.

 

Web Application Upgrade System (cs_webdbupgrade) [top]

Upgrade your database and application at the same time.  With any system that lingers for more than a few months, upgrades become standard; those upgrades tend to involve schema changes, even data changes, along with updated code.  If the database doesn't match the code (or vice-versa), data corruption can occur or the application might stop altogether, so these upgrades tend to happen at night, manually, sometimes with scripts that are written on-the-fly.

Instead, simply implement a version number for a part of the system or the whole thing, and add a couple lines of code to check that the database version matches the code version.  Scripts can then be written ahead of time, tested on a different server as needed: when the time comes, update the code on the server with the new version and the upgrades, and this system will run those scripts to seemlessly upgrade the site without incurring any downtime.

If your application is smart enough to use PostgreSQL, the entire upgrade will run inside of a transaction: in the event of failure, the transaction will be rolled-back, and a lock file will ensure that the new code (attached to the old database) will not run until someone fixes the problem.  It is perfect for web applications that are installed at multiple remote locations: CS-Project utilizes this system to make sure existing installations can be upgraded without any adminstrator intervention.  Upgrades made crazy easy!

 

Lock File System (cs_lockfile) [top]

Certain operations just shouldn't trip over each other, such as with an application upgrade: enter the lock file system.  It's a pretty simple thing, really, where a file of a certain name is written (such as "upgrade.lock"): the first operation checks for it and writes the file.  If a second attempt to perform the upgrade starts, it will fail, because the lock file is already in place.  Simple!

---

---