SurvLoop Package's File & Folder Layout

Updated March 13, 2019

Laravel is an MVC (Model View Controller), and the SurvLoop package is primarily structured accordingly...

wikiworldorder/survloop

  • composer.json: Defines more packages required by SurvLoop, as well as easier references to some packages.
  • src: Repository's main source code.
    • routes.php: All of SurvLoop's routing happens here, passing a url request to the right Controller.
    • SurvLoopServiceProvider.php: SurvLoopServiceProvider manages which package files and folders need to be copied to elsewhere in the system. This mostly just runs after installation, and perhaps of some other code updates.
    • Controllers: Most of the PHP algorithms and logic which process and manipulate data, and call Views to output the proper results.
      • Admin: These PHP classes controll both all admin tools for managing survloop, but also handles routing for SurvLoop pages and surveys which require any user login.
      • Auth: A few Laravel authorization classes customized by SurvLoop.
      • Globals: These classes can be easily accessed from both Controllers and Views.
      • Middleware: A few Laravel files overwritten by SurvLoop.
      • Stats: These classes are used by SurvLoop to manage the more complicated statistical needs, charts, and graphs.
      • Tree: This is really the core trunk of SurvLoop, classes which manage the branching trees which generate all surveys, pages, etc.
    • Database: Includes migration and seeder files which Laravel can use to install SurvLoop.
    • Models: Copies of all the Eloquent Models used by this package, generated by this same SurvLoop installation.
    • Uploads: Contains images and photos in SurvLoop's default media gallery, most are simply needed for SurvLoop branding.
    • Views: Includes Blade Templates which are called by controllers, and where most of SurvLoop's HTML, Javascript, and CSS can be found. Templates for...
      • admin: general SurvLoop-standard admin interfaces
        • db: admin database design tools
        • tree: admin survey and page design tools
      • auth: user authentication, customizing Laravel's style
        • passwords: user password tools
      • css: cascading style sheets for the SurvLoop engine
      • elements: smaller site design or usability elements
      • emails: sending emails via the installation
      • errors: web site error pages
      • forms: generating survey forms and compartmentalized input tools
      • js: javascript which runs lots of user experience for the SurvLoop engine
      • reports: generating reports, graphs, and geographic maps
  • tests: Holding place to remind me to add as much unit testing as possible and appropriate.

wikiworldorder/survloop-libraries

  • src: Third-party code libraries which SurvLoop incorporates.

Structure of Classes & Objects

This section provides a top-level map of the Controllers folder, and how its most influential classes and objects relate to each other.

Some of these long chains of extensions were simply steps toward breaking up long files. I hope to keep splitting out functions which don't need to load in some thick trunks.


Routes are largely directed through...

  • SurvLoop.php
    • extends SurvCustLoop
      • extends PageLoadUtils
  • Admin/AdminController
      • extends SurvLoopController
      • instantiates PageLoadUtils
    • extended by Admin/AdminDatabaseInstall
    • extended by Admin/AdminDBController
    • extended by Admin/AdminTreeController
      • instantiates Tree/TreeSurvAdmin

Down the line, I hope to replace AdminDBController and AdminTreeController with admin-only SurvLoop-generated forms. And all other admin tools.


The Globals object is loaded into $GLOBALS["SL"] and primarily provides lookups and tools to be accessible from both Controllers and Views...

  • Globals
    • extends GlobalsImportExport
      • extends GlobalsTables
        • extends GlobalsStatic
    • instantiates Geographs


The Tree Trunk is the single largest block of the engine which generates all the surveys and pages for SurvLoop...

  • Tree/TreeNodeSurv
    • extends Tree/TreeNodeCore
  • Tree/TreeSurvAdmin
    • extends Tree/TreeSurvNodeEdit
      • extends Tree/TreeSurvForm
        • extends Tree/TreeSurvFormUtils
          • extends Tree/TreeSurvFormLoops
            • extends Tree/TreeSurvFormVarieties
              • extends Tree/UserProfile
                • extends Tree/TreeSurvInput
                  • extends Tree/TreeSurvUpload
                    • extends Tree/TreeSurv
                      • extends Tree/TreeSurvReport
                        • extends Tree/TreeSurvBasicNav
                          • extends Tree/TreeSurvProgBar
                            • extends Tree/TreeSurvLoad
                              • extends Tree/TreeSurvConds
                                • extends Tree/TreeSurvAPI
                                  • extends Tree/TreeCoreSess
                                    • extends Tree/TreeCore
                                      • extends SurvLoopController
                              • instantiates Tree/SurvData
                                • instantiates SurvDataTestsAB


The Stats Engine is hopefully most often called by a tree...

  • SurvStatsGraph
    • extends SurvStatsChart
      • extends SurvStats
        • extends SurvStatsCache
          • extends SurvStatsFilts
            • extends SurvStatsCore
  • SurvTrends
    • extends SurvStatsCore


  • SurvLoopController
    • instantiates Searcher
    • instantiates Globals
    • instantiates Tree Trunk (client or TreeSurvForm)

Existing Plans for the Code Base its Structures

  • Start adding unit tests to functions and ideally whole files.
  • Break off any independent components from being within the Tree Trunk and Globals, which can instead instantiate side-classes when on demand.
  • Expand Globals from being "focused on one database and tree", to "able to load [caches of] all the database and tree structures needed for a page load.
  • Shift to PageLoadUtils being even more the core trunk of a page load, instead of the Tree Trunk.
  • Further clarify and separate the distinctions and relationships between PageLoadUtils stuff, Globals stuff, Tree Trunk stuff, and Searcher stuff.
  • Adding unit test to as many functions as possible.
  • Adding comments to the remaining functions.
  • Replace all admin tools with forms generated by SurvLoop. #SelfReplicatingGUI/CMS

Client Packages

A client package running atop the SurvLoop engine will automatically load client-customized extensions of these classes as well...

  • Client/Client
    extends
    SurvLoop/Tree/TreeSurvForm
  • Client/ClientAdminMenu
    extends
    SurvLoop/Admin/AdminMenu
  • Client/ClientAdmin
    extends
    SurvLoop/Admin/AdminController
  • Client/ClientSearcher
    extends
    SurvLoop/Searcher