/PHP-Sprint-Framework

A PHP web-project template.

Primary LanguagePHP

SPRINT-V3

Table of Contents


About The Project

Sprint is a project I made to be able to pass my web development exams without having to depend on any frameworks. What exactly is Sprint? Calling Sprint a framework would be a bit of an overstatement. It's a project template containing a handful of useful features, which allows any programmer to deploy a website or webapp without hassle.

Why use Sprint when there are a lot of great frameworks that contain a lot of features? Sprint doesn't do a lot of things, unlike wordpress or laravel for example. But it's very quick and it's easy to modify. Using a framework like wordpress to create a website always makes me feel like I'm using sledgehammer to crack a nut.

Apps written using Sprint


Features

In short? Pretty urls, forced https, MVC layout, database class, resource control, resource piling and more.

A little more in depth:

  • Easy to use pretty url system
    • /about instead of /about.html
  • Premade MVC folder layout
  • Forced HTTPS setting
  • Simple database class
    • To easily switch between production and deployment databases
  • Resource spreading feature
    • Want to load a certain script at the end of the body on every page? easy.
  • Request limiting feature
    • Compiles all your resources upon requests
  • Resource free pages
    • Have a controller page on which you don't want to load any resources? add it to the content-blocklist

Default resources

Sprint is packaged with a few resources that I consider to be useful. These resources are recommendations, and I often use them myself, they are not requirements.

Getting Started

To start, download the project. Create a new directory, I'm going to be using my_project for examples.

It is possible to add any resource to this project if you want to, I will explain this in the resources section. (For example charts.js or any front-end library)

Prerequisites

To work with Sprint you need a webserver and a PHP environment. I recommend XAMPP. Make sure your sprint project is inside of a webserver directory (like htdocs).

There are no installation steps, sprint configuration is purely file based.

Creating pages

Adding a page
The areas directory contains all your pages, each directory resembles a page. To create a new /page, create a directory in areas. Within this directory add another directory called views. Add an index.php file to this directory. You should end up with the following path:

areas/my_page/views/index.php

This new page is now accessible as localhost/my_project/my_page. (or as localhost/my_page if you're using your entire htdocs as the project root)

Removing stock areas
In the areas folder you will find the controller and index area, you can remove them. The controller and index area only function as examples. The 404 area will be displayed when an unknown area is being called by a user, you can modify it to your liking.

Stock area behavior
By default, two area names have special characteristics, these areas are index and controller. The index area functions as the index of your project, this means that it's accessible at localhost/my_project/index but also at localhost/my_project.

Resources

In assets/resources you will find a custom directory which contains an empty stylesheet and script file, which have already been added to the resource system. This means they will be included on every page except for pages that have been added to the resource-blacklist. More about the resource-blacklist here.

To use custom stylesheets and script files, I would very much recommend you to use the preload and afterload system (instead of directly linking to them within your html).

Preload & Afterload
In the sprint directory you will find resource-preload.php and resource-afterload.php. In these files you can declare two types of resources:

  1. Resources that should be loaded before the first contentful paint - resource-preload.php
  2. Resources that should be loaded at the end of the body - resource-afterload.php

Generally speaking, you want to add your stylesheets to preload and your scripts to afterload. Using this system will improve your user experience because big scripting files are being loaded after the content is displayed.

Adding resources
As an example, add the following line to your resource-preload.php to add a new resource (in this case "zebra.css"):

import("assets/resources/zebra/zebra.css");

The import() function recognizes different types of files and it will generate the right type of <link> accordingly.

Resource stacking
Resource stacking is a sprint feature that compiles all your resources together with your html, to lower the amount of requests made. This feature generally improves load times. The idea is that making one big request is better than making tons of small requests. It can be enabled/disabled in sprint/settings.php.

WARNING Resource stacking can only be used when all your preload and afterload resources are stored locally.

Settings

$project_version

Type: Int
Default value: 1

Used to update client-side cached resources. Changing this value will also change all the resource urls, causing a forced recache.

$execution_mode

Type: String
Default value: 'strict'
Possible values: 'quiet', 'oblivious', 'strict'

Sprint uses a small set of internal functions, these funtions can display debug information:

  • quiet: display no debug information
  • oblivious: display debug information
  • strict: display debug information, and exit; after encountering issues

$resource_blacklist

Type: Array
Default value: ["controller"]

This value contains a list of pages on which you don't want to load any of the resources declared in resource-preload.php and resource-afterload.php. Imagine you have a PHP controller area that is only being posted to, adding this area to the resource_blacklist will be beneficial since the controller doesn't require any of the stylesheets or scripts.

The resource_blacklist is also useful if you have a specific page that doesn't require any of the stylesheets or scripts.

$use_resource_stacking

Type: Bool
Default value: TRUE

Resource stacking is a sprint feature that compiles all your resources together with your html, to lower the amount of requests being made. This feature generally improves load times. The idea is that making one big request is better than making tons of small requests. It can be enabled or disabled.

WARNING Resource stacking can only be used when all your preload and afterload resources are stored locally.

$use_forced_https

Type: Bool
Default value: FALSE

Bool used to force users to use HTTPS.

$database_model

Type: String (String by default)
Default value: 'local'

Setting used to switch between credential set. These sets are stored in $database_credentials.

This can be useful if there are differences between your local and your production database.

$database_credentials

Type: Array
Default value:
    array(
        'local' => array('localhost', 'root', ''),
        'production' => array('localhost', 'root', '')
    )

Used to store all available database credential sets.

Services

sprint/services.php is a file used to load "services". Services are snippets of code used to trigger specific behaviours. Services are loaded for every view, but specific load behaviour can also be set.

Example services.php

<?php

include("sprint/services/rate-limit.php");

if (isset($_GET['page']) && $_GET['page']=='some_page') {
    include("sprint/services/some_other_service.php");
}

Services are to be stored in sprint/services/, an example service can be seen here.



Database and Controller

Sprint does not require a database to function, but it does contain a set of useful examples. As explained in the settings section, you can switch between sets of database credentials by toggling $database_model (in sprint/settings.php).

In general, I like to use a single controller to which I do all my posts. Sprint includes this controller and you can delete it if you want to, it's not a requirement.

In areas/controller/functions.php you can find SQL query examples and in areas/index/views/index.php you can find an example on how to retrieve data from the controller using Jquery.

Icons

In assets you can find two images called favicon.png and logo.png. favicon.png will be used as the favicon of your project, and logo.png will be used when a user creates a shortcut to your project on a mobile device.

License

MIT License Copyright (c) 2020 Storm-Julian Tersteeg

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.