Back to top

Rack

Rack — A framework, typically with rails, bars, hooks, or pegs, for holding or storing things.

Rack is a small and simple boilerplate/framework for PHP based web applications that are integrated with the login API of the Cover website. It aims to ease the creation of websites or microservices that only need a small number of forms, tables and views and to provide a familiar project structure among most of Cover's PHP projects. Additionally, anybody with basic OOP skills and a basic understanding of the web should be able to easily comprehend the framework and setup a website.

Rack implements the following features:

  • Basic templates with template inheritance
  • Form rendering and validation (server side)
  • SQL injection safe database interactions
  • User authentication through the Cover API

Future improvements:

  • CSRF protection (this is a desired feature).
  • Escaping values by default in templates.
  • Broader coverage of HTML form input types
  • …and more! Please share your suggestions here.

Rather than providing a fully-featured API, Rack aims to provide just enough functionality to cover the basic needs. Projects with more complicated requirements should extend, subclass and/or override Rack code where needed to add functionality.

Getting Started

Installation

Clone (or fork or download) the Bitbucket repository into the root folder of your project and you're ready to go!

Project structure

Projects using Rack adhere to the following structure:

📁 Project
├ 📁 include
│ ├ 📁 models
│ │ ├ 📁 migrations
│ │ ├ Model.class.php
│ │ └ … (model definitions)
│ ├ config.php
│ ├ include.php
│ └ … (other Rack logic php files)
├ 📁 static
│ ├ 📁 css
│ ├ 📁 js
│ ├ 📁 img
│ └ … (other static content)
├ 📁 templates
│ ├ error.phtml
│ ├ index.phtml
│ ├ layout.phtml
│ └ … (templates for other views)
├ index.php
└ … (other views)

The include folder is meant Rack's internal logic and possible application-specific extensions to it. It should not contain any views, templates or static files.

Configuration

A config file include/config.php is needed for Rack to work properly. A default configuration is provided in include/config.php.default which can be copied to initialize the config.php file. Remember that this config file is likely to contain passwords, so it should be added to the .gitignore file to prevent it from showing up in Git repositories. Do not forget to change it's file permissions to hide it from other users on the system. This can be done with the following command: chmod 700 include/config.php. All available configuration options are listed here.

Creating views

Now, you're ready to create views. A view is a php file in the project's root folder. Every view should include (or require) the include/init.php file, to load the Rack functionality. An example of a view that renders the template templates/index.php is provided below:

index.php
<?php
require_once 'include/init.php';
 
// Create and run home view
$view = new TemplateView('index');
$view->run();

Glossary

  • Committee login: The internal mnemonic ID of a committee. It can be found as the value of the committee parameter in the url of the committee page on the Cover website. For example, login for the AC/DCee is webcie as can be seen in their url https://www.svcover.nl/commissies.php?commissie=webcie. Their is no guaranteed relationship between a committee login and its account name on the server, but there is always a working email address committee_login@svcover.nl.
  • Committee name: The real name of a committee. Like AC/DCee, IntroCee or StudCee.
  • Cover API: The API of the Cover website, accessible through https://www.svcover.nl/api.php
  • Cover session: The session of a logged in user of the Cover website.
  • Cover website: Cover's home on the web, https://www.svcover.nl

API Reference

The following pages contain short documentation of the available classes and functions. They are meant to provide an overview of the features and dataflows. Anybody in need of implementation specific detail is advised to inspect the source code.

Versions

  • 1.1 (2019-05-10, Current)
    • Added CSV view to ModelView.
    • Added optional Sentry support.
    • Model→create() now returns the inserted ID.
    • Various minor improvements/fixes
  • 1.0 (2018-05-26)
    • Initial version, based on various projects.

documentation/rack/start.txt · Last modified: 2022/04/03 16:00 by 127.0.0.1