Difference between revisions of "Slib"

From ProgClub
Jump to: navigation, search
(→‎Misc: More things to do!)
 
(42 intermediate revisions by the same user not shown)
Line 3: Line 3:
 
== Project status ==
 
== Project status ==
  
Under way. Not released yet, there's stuff [[Slib#TODO|TODO]].
+
Version 0.1 has been released and it's being used.
 +
 
 +
Version 0.2 is under way and isn't ready for release yet. There's stuff [[Slib#TODO|TODO]].
  
 
== Contributors ==
 
== Contributors ==
Line 9: Line 11:
 
Members who have contributed to this project. Newest on top.
 
Members who have contributed to this project. Newest on top.
  
* [[User:John|John]]
+
* [[User:John|John Elliot V]]
  
 
All contributors have agreed to the terms of the [[ProgClub:Copyrights#ProgClub_projects|Contributor License Agreement]]. This excludes any upstream contributors who tend to have different administrative frameworks.
 
All contributors have agreed to the terms of the [[ProgClub:Copyrights#ProgClub_projects|Contributor License Agreement]]. This excludes any upstream contributors who tend to have different administrative frameworks.
Line 15: Line 17:
 
== Copyright ==
 
== Copyright ==
  
Copyright 2011, [[Slib#Contributors|Contributors]]. Licensed under [https://www.apache.org/licenses/LICENSE-2.0 APACHE 2.0].
+
Copyright 2011-2014, [[Slib#Contributors|Contributors]]. Licensed under [https://www.apache.org/licenses/LICENSE-2.0 APACHE 2.0].
 +
 
 +
=== Libraries ===
 +
 
 +
The Slib software uses the following libraries:
 +
 
 +
* [https://github.com/browscap browscap]: [https://github.com/browscap/browscap/blob/master/LICENSE MIT License]
 +
* [https://www.maxmind.com/en/opensource MaxMind GeoIP]: You need a [https://www.maxmind.com/en/sitelicense GeoIP Site License] to use this software. See the [https://www.maxmind.com/en/faq FAQ]
 +
* Inflector: [https://www.gnu.org/licenses/lgpl.html GNU Lesser General Public License]
 +
* [https://github.com/rchouinard/phpass PHPass]: [https://github.com/rchouinard/phpass/blob/master/LICENSE MIT License]
 +
* [http://getbootstrap.com/ Twitter Bootstrap]: [http://getbootstrap.com/getting-started/#license-faqs MIT License]
 +
* [https://jquery.org/ jQuery]: [https://jquery.org/license/ MIT License]
 +
* [http://jqueryui.com/ jQuery UI]: [https://jquery.org/license/ MIT License]
 +
* [http://jqueryvalidation.org/ jQuery Validation]: MIT License
 +
* [http://nicedit.com/ NicEdit]: [http://nicedit.com/license.php MIT License]
 +
* [https://github.com/twitter/typeahead.js/ typeahead.js]: MIT License
 +
* [https://github.com/aFarkas/html5shiv html5shiv]: [https://github.com/aFarkas/html5shiv/blob/master/MIT%20and%20GPL2%20licenses.md MIT and GPL2 licenses]
  
 
== Source code ==
 
== Source code ==
Line 21: Line 39:
 
The repository can be browsed online:
 
The repository can be browsed online:
  
  https://www.progclub.org/pcrepo/slib/trunk
+
  https://www.progclub.org/pcrepo/slib/branches
  
 
The code for slib is publicly available from svn:
 
The code for slib is publicly available from svn:
Line 29: Line 47:
 
Or privately available for read-write access:
 
Or privately available for read-write access:
  
  https://www.progclub.org/svn/pcrepo/slib/trunk
+
  https://www.progclub.org/svn/pcrepo/slib/branches
  
 
== Links ==
 
== Links ==
Line 38: Line 56:
  
 
The software provides a web-framework/toolkit for PHP applications.
 
The software provides a web-framework/toolkit for PHP applications.
 +
 +
=== A new approach to dependency injection ===
 +
 +
The slib framework has a new approach to dependency injection. If you want to provide a mock/instrumented instance of any of the framework classes all you have to do is define the ClassName that you want to inherit from the SlibClassName. Your ClassName file will automatically be instantiated by the factory method that Creates/Loads your implementation. The way this works is that slib registers a [https://www.progclub.org/pcrepo/slib/trunk/src/mock-loader.php?view=markup mock-loader] that will generate a concrete type if no concrete type is defined and the base implementation operates on the concrete type.
 +
 +
=== Database interface ===
 +
 +
There is a [https://www.progclub.org/pcrepo/slib/trunk/src/db/SlibDatabase.php?view=markup Database] interface. Has support for [https://www.progclub.org/pcrepo/slib/trunk/src/db/DataSort.php?view=markup DataSort] sorting and [https://www.progclub.org/pcrepo/slib/trunk/src/db/DataPage.php?view=markup DataPage] pagination. There is no filtering support yet.
 +
 +
=== Database schema management ===
 +
 +
There is a [https://www.progclub.org/pcrepo/slib/trunk/src/db/SlibDatabaseUpgrader.php?view=markup DatabaseUpgrader] that handles database schema migrations. There was some talk of factoring the SQL out into .sql files, but I think this format is easier to maintain/reference as all the table definitions are right there in the source.
 +
 +
=== Asset management ===
 +
 +
There is a [https://www.progclub.org/pcrepo/slib/trunk/src/class/SlibResourceManager.php?view=markup ResourceManager] and a [https://www.progclub.org/pcrepo/slib/trunk/bin/compile.php?view=markup compiler]. The compiler bundles CSS and JavaScript, the ResourceManager handles requests for assets. Note: the compiler automatically generates .gz files for all assets so the ResourceManager can return them.
 +
 +
Support for graphics, style, scripts, and caching is provided by the ResourceManager.
 +
 +
=== Settings management ===
 +
 +
There is a [https://www.progclub.org/pcrepo/slib/trunk/src/class/SlibSettings.php?view=markup Settings] manager. It provides a layered approach to user settings. First we try to get a setting from the [https://www.progclub.org/pcrepo/slib/trunk/src/orm/SlibSessionSettings.php?view=markup Session], then the [https://www.progclub.org/pcrepo/slib/trunk/src/orm/SlibUserSettings.php?view=markup User] otherwise global default.
 +
 +
=== Session management ===
 +
 +
User sessions are managed by the [https://www.progclub.org/pcrepo/slib/trunk/src/orm/SlibSession.php?view=markup Session] component. Supports user login.
 +
 +
=== Authorisation management ===
 +
 +
There is an [https://www.progclub.org/pcrepo/slib/trunk/src/class/SlibAuth.php?view=markup Auth] component that defines authorisations for actions.
 +
 +
=== Role-based security ===
 +
 +
There is first-class support for [https://www.progclub.org/pcrepo/slib/trunk/src/orm/SlibUser.php?view=markup User] and [https://www.progclub.org/pcrepo/slib/trunk/src/orm/SlibRole.php?view=markup Role] facilitating role-based security.
  
 
=== URI/URL management ===
 
=== URI/URL management ===
Line 97: Line 149:
 
  $this->assertSame( "https://www.progclub.org/wiki/Main_Page//test", strval( $uri ) );
 
  $this->assertSame( "https://www.progclub.org/wiki/Main_Page//test", strval( $uri ) );
  
=== Misc ===
+
=== TODO ===
  
* SQL files in /etc/slibdb/12345-table-name.sql
+
* Support for Min/Max defaults and specific validation
* database upgrader to use SQL files one at a time from /etc/slibdb/*.sql
+
* TableView->name for use in sort/page/etc slugs (defaults to 'defalut')
* database versions: global() and partition( $id )
+
* TableView->read_{selected,searched}_columns and ensure they are valid.
* generate and auto-load mocks in /var/tmp
+
** If they are not valid remove the offending parameter and redirect
* user creation includes user's partition being created
+
* Joins omitted by selected columns
* database interface, Database inherits SlibDatabase (sorting/pagination/filtering support)
+
* Per entity database references (remove dependency on db singleton)
** db()
+
* Partition management
** DataSort
+
* DB Aggregator
** DataPage
+
* Auto-join
** DataQuery
+
* Tabulation view
** DatabaseSchema inherits SlibDatabaseSchema
+
* Many-to-Many
* database upgrade DatabaseUpgrade inherits SlibDatabaseUpgrade
+
* Forms-processing
** dbu()
+
* require* library
* settings management (session, user, global)
+
* Entity->get_sid( ref, state )
** sm()->settings
+
* Entity::Create( serialized-state, is_new ). Checks schema()->cache before creating.
** SettingsManager inherits SlibSettingsManager
+
* Entity::LoadBySid
** Setting inherits SlibSetting
+
* Entity::LoadByKey
** GlobalSettings, UserSettings, SessionSettings inherits SlibSettings
+
* Family album
* session management (login, settings/state)
+
* Multiple accounts / sharing (by partitions)
** sm()
+
* Pay for printing/binding
** SessionManager inherits SlibSessionManager
+
* Address with photos/map
* auth management
+
* Budget keeper
** auth()->can_edit_post( $sm )
+
* CV/resume
* user/group management (auth, permissions)
+
* Fancy Invitation/RSVP
** sm()->user and user->groups
+
* Library (register of books owned)
** User inherits SlibUser
+
* Fixing the object-relational impedence mismatch by using models for OLTP and arrays for reporting (e.g. HTML tables, pagination, sorting, joining, filtering, etc.)
** Group inherits SlibGroup
+
* Session, Browser, User, Global config
* resource management (graphics, style, scripts, caching)
+
* Principal (Browser, User) create table principal ( id, type(browser/user), {broswer,user}id )
** rm()
+
* Contact and Service
 +
* Articles and books. Draft and published. Shared with contact
 +
* TODO list
 +
* Link redirector and bookmarks
 +
* File uploads and picture gallery. Public/private/shared.
 +
* Calendar, date-picker
 +
* Timesheets
 +
* Surveys/Questionnaires
 +
* Interactive chat
 +
* Session monitor (follow user sessions in real time in your browser, you see what they see)
 +
* Email client
 +
* RSS feeds
 +
* detect preferred language and if not English ask if the user will translate the content
 +
** offer one month free at bkdb.com in exchange
 +
* table->ref( key_name, col_nam, ref_table, ref_col ) in Schema
 +
* Instrument SlibDatabase and log SQL/time/etc to slib__sql_monitor
 
* graphics management (database, scale, cache)
 
* graphics management (database, scale, cache)
 
** gm()
 
** gm()
Line 163: Line 230:
 
** same schema in all databases
 
** same schema in all databases
 
* create partition_* databases, one for each partition
 
* create partition_* databases, one for each partition
 +
* partition load order and default partition in settings
 +
* database versions: global() and partition( $id )
 +
* user creation includes user's partition being created
  
 
== Technical specification ==
 
== Technical specification ==
Line 172: Line 242:
 
Things to do, in rough order of priority:
 
Things to do, in rough order of priority:
  
 +
* Schema load
 +
* Partition: id, server, database, schema
 +
* Service Map: _gid, _app, _web, _000001 (partition 1)
 +
* gid: 0 = Null Object; +ve for existing GID, -ve for new GID
 +
* html2text..?
 +
* Internationalisation using _ function
 +
* Language messages in HTML, e.g. _('John's Message.')
 +
* Plural/singular
 +
* Upgrade GIT: Int24, Int32, Int64
 
* Create the project in svn
 
* Create the project in svn
 
* Document functional specification
 
* Document functional specification
 
* Document technical specification
 
* Document technical specification
 
* Copy in existing code
 
* Copy in existing code
 
[[Category:TODO]]
 
  
 
== Done ==
 
== Done ==
Line 183: Line 260:
 
Stuff that's done. Latest stuff on top.
 
Stuff that's done. Latest stuff on top.
  
 +
* [[User:John|JE]] 2014-05-14: documenting functional specification
 
* [[User:John|JE]] 2011-12-08: created project page
 
* [[User:John|JE]] 2011-12-08: created project page
  
Line 191: Line 269:
 
You probably want to setup an svn:externals from your svn repository to the public release tag:
 
You probably want to setup an svn:externals from your svn repository to the public release tag:
  
  http://www.progclub.org/svnro/pcrepo/slib/tags/latest
+
  https://www.progclub.org/svn/pcrepo/slib/tags/latest
  
That way you'll get changes to the framework as they're released.
+
That way you'll get changes to the framework as they're released. Beware, the interface is super volatile, it won't stabalise for a while.

Latest revision as of 16:18, 11 December 2017

Slib is the ProgClub PHP framework software. That's the software that provides a framework for your PHP applications. For other projects see projects.

Project status

Version 0.1 has been released and it's being used.

Version 0.2 is under way and isn't ready for release yet. There's stuff TODO.

Contributors

Members who have contributed to this project. Newest on top.

All contributors have agreed to the terms of the Contributor License Agreement. This excludes any upstream contributors who tend to have different administrative frameworks.

Copyright

Copyright 2011-2014, Contributors. Licensed under APACHE 2.0.

Libraries

The Slib software uses the following libraries:

Source code

The repository can be browsed online:

https://www.progclub.org/pcrepo/slib/branches

The code for slib is publicly available from svn:

https://www.progclub.org/svn/pcrepo/slib/tags/latest

Or privately available for read-write access:

https://www.progclub.org/svn/pcrepo/slib/branches

Links

No links at this time.

Functional specification

The software provides a web-framework/toolkit for PHP applications.

A new approach to dependency injection

The slib framework has a new approach to dependency injection. If you want to provide a mock/instrumented instance of any of the framework classes all you have to do is define the ClassName that you want to inherit from the SlibClassName. Your ClassName file will automatically be instantiated by the factory method that Creates/Loads your implementation. The way this works is that slib registers a mock-loader that will generate a concrete type if no concrete type is defined and the base implementation operates on the concrete type.

Database interface

There is a Database interface. Has support for DataSort sorting and DataPage pagination. There is no filtering support yet.

Database schema management

There is a DatabaseUpgrader that handles database schema migrations. There was some talk of factoring the SQL out into .sql files, but I think this format is easier to maintain/reference as all the table definitions are right there in the source.

Asset management

There is a ResourceManager and a compiler. The compiler bundles CSS and JavaScript, the ResourceManager handles requests for assets. Note: the compiler automatically generates .gz files for all assets so the ResourceManager can return them.

Support for graphics, style, scripts, and caching is provided by the ResourceManager.

Settings management

There is a Settings manager. It provides a layered approach to user settings. First we try to get a setting from the Session, then the User otherwise global default.

Session management

User sessions are managed by the Session component. Supports user login.

Authorisation management

There is an Auth component that defines authorisations for actions.

Role-based security

There is first-class support for User and Role facilitating role-based security.

URI/URL management

The SlibUri class and its associates provide an interface for reading and manipulating URIs. The following diagram illustrates the six types of URI supported and the component pieces:

SlibUriHierarchy-1.png

The software has been specifically designed to cater to specialised URI handling, such as seen with SlibMailtoUri which extends SlibUri with 'mailto' specific API such as get_mail_user(), get_mail_domain(), get_mail_subject(), etc., etc. At this time the only specialised URI is for mailto links, all other schemes are handled with URI types 1 to 5, most of them being a 4.

For a list of all documented URI schemes see URI scheme at Wikipedia. There is a code generator which generates the strong-typed URIs based on documented schemes. The idea is that the design caters for URIs to be scheme specific, but the design doesn't need to be done immediately. Presently the only real URI support is for schemes: http, https, file and mailto, the rest are generic for the time being.

Note: because of the decision to use 'strong-typed' classes on the API it is possible to do something odd. For example I could create a SlibHttpUri using ::Parse(...) and then on that URI change the scheme to 'mailto', I will then have a SlibHttpUri that reports its scheme as 'mailto', not 'http'. It's not a great design, but hey, it works if you don't push it and importantly: it's done!

Here's an example of using SlibUri for getting URL components:

$uri = SlibUri::Parse( "https://www.progclub.org/wiki/Main_Page", '/wiki' );
$this->assertSame( 'https', $uri->get_scheme() );
$this->assertSame( 'www.progclub.org', $uri->get_host()->to_string() );
$this->assertSame( '/wiki', $uri->get_base() );
$this->assertSame( '/Main_Page', $uri->get_path()->to_string();

$uri = SlibUri::Parse( "mailto:jj5@progclub.org?subject=test" );

$this->assertSame( 'jj5', $uri->get_mail_user() );
$this->assertSame( 'progclub.org', $uri->get_mail_domain()->to_string() );
$this->assertSame( 'test', $uri->get_mail_subject() );

$uri = SlibUri::Parse( "https://www.progclub.org/pcwiki/index.php?title=Main_Page&action=edit" );

$this->assertSame( '/pcwiki/index.php', $uri->get_path()->to_string() );
$this->assertSame( 'pcwiki', $uri->get( 1 ) );
$this->assertSame( 'index.php', $uri->get( 2 ) );
$this->assertSame( 'index.php', $uri->get_filename() );
$this->assertSame( 'php', $uri->get_extension() );
$this->assertSame( 'Main_Page', $uri->get( 'title' ) );
$this->assertSame( 'edit', $uri->get( 'action' ) );

And here's an example of using SlibUri to build URLs:

$uri = SlibUri::Parse( "https://www.progclub.org/wiki/Main_Page", '/wiki' );

$uri = $uri->to_builder();

$uri->set( 'q', 'testing' );

$this->assertSame( "https://www.progclub.org/wiki/Main_Page?q=testing", strval( $uri ) );

$uri->set( 'a', array( 1, 2, 3 ) );

$this->assertSame( "https://www.progclub.org/wiki/Main_Page?q=testing&a=1&a=2&a=3", strval( $uri ) );

$uri->clear( 'q' );
$uri->clear( 'a' );

// set the 4th path part:
$uri->set( 4, 'test' );

$this->assertSame( "https://www.progclub.org/wiki/Main_Page//test", strval( $uri ) );

TODO

  • Support for Min/Max defaults and specific validation
  • TableView->name for use in sort/page/etc slugs (defaults to 'defalut')
  • TableView->read_{selected,searched}_columns and ensure they are valid.
    • If they are not valid remove the offending parameter and redirect
  • Joins omitted by selected columns
  • Per entity database references (remove dependency on db singleton)
  • Partition management
  • DB Aggregator
  • Auto-join
  • Tabulation view
  • Many-to-Many
  • Forms-processing
  • require* library
  • Entity->get_sid( ref, state )
  • Entity::Create( serialized-state, is_new ). Checks schema()->cache before creating.
  • Entity::LoadBySid
  • Entity::LoadByKey
  • Family album
  • Multiple accounts / sharing (by partitions)
  • Pay for printing/binding
  • Address with photos/map
  • Budget keeper
  • CV/resume
  • Fancy Invitation/RSVP
  • Library (register of books owned)
  • Fixing the object-relational impedence mismatch by using models for OLTP and arrays for reporting (e.g. HTML tables, pagination, sorting, joining, filtering, etc.)
  • Session, Browser, User, Global config
  • Principal (Browser, User) create table principal ( id, type(browser/user), {broswer,user}id )
  • Contact and Service
  • Articles and books. Draft and published. Shared with contact
  • TODO list
  • Link redirector and bookmarks
  • File uploads and picture gallery. Public/private/shared.
  • Calendar, date-picker
  • Timesheets
  • Surveys/Questionnaires
  • Interactive chat
  • Session monitor (follow user sessions in real time in your browser, you see what they see)
  • Email client
  • RSS feeds
  • detect preferred language and if not English ask if the user will translate the content
    • offer one month free at bkdb.com in exchange
  • table->ref( key_name, col_nam, ref_table, ref_col ) in Schema
  • Instrument SlibDatabase and log SQL/time/etc to slib__sql_monitor
  • graphics management (database, scale, cache)
    • gm()
  • file management (database, upload, cache)
    • fm()
  • form management (validation, submission(POST)/query(GET))
    • form()
    • Submission inherits SlibSubmission
    • Query inherits SlibQuery
    • Validator inherits SlibValidator
  • content management (news, book, page)
    • cm()
    • Article (News) inherits SlibArticle (date, title, description, html)
    • Book inherits SlibBook
    • Chapter inherits SlibChapter
    • Page inherits SlibPage
  • translation facilities for content and services
    • tm()
  • access logging (all HTTP activity)
    • log()
  • error logging (write failed logins to error log, pick up with fail2ban)
    • log()->error()
  • request management (HTTP input/output)
    • req()
    • redirection support: req()->goto( $url )
    • cookie support: req()->cookie( $name, $etc )
    • HTTP headers support: req()->header( ... )
  • Category (for content, graphics, files)
  • Tag (for content, graphics, files)
  • Feed provider
    • feed()
  • sharding:
    • main_db, partition_*_db
    • log_db(), db( $partition_id )
    • same schema in all databases
  • create partition_* databases, one for each partition
  • partition load order and default partition in settings
  • database versions: global() and partition( $id )
  • user creation includes user's partition being created

Technical specification

TODO.

TODO

Things to do, in rough order of priority:

  • Schema load
  • Partition: id, server, database, schema
  • Service Map: _gid, _app, _web, _000001 (partition 1)
  • gid: 0 = Null Object; +ve for existing GID, -ve for new GID
  • html2text..?
  • Internationalisation using _ function
  • Language messages in HTML, e.g. _('John's Message.')
  • Plural/singular
  • Upgrade GIT: Int24, Int32, Int64
  • Create the project in svn
  • Document functional specification
  • Document technical specification
  • Copy in existing code

Done

Stuff that's done. Latest stuff on top.

  • JE 2014-05-14: documenting functional specification
  • JE 2011-12-08: created project page

Notes for implementers

If you are interested in incorporating ProgClub slib into your project, here's what you need to know:

You probably want to setup an svn:externals from your svn repository to the public release tag:

https://www.progclub.org/svn/pcrepo/slib/tags/latest

That way you'll get changes to the framework as they're released. Beware, the interface is super volatile, it won't stabalise for a while.