A PHP Micro Framework - Lightning Fast - Easy to Develop
Switch branches/tags
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
do
engine
library
temp
uploads
view
.gitattributes
.gitignore
.htaccess
README.md
_config.yml
composer.json
index.php
install.sql
install_no_cms.sql
phpdox.xml

README.md

Lectric PHP Micro Framework!

Mount Alpine has written a tutorial series that walks developers through the coding of this framework! View "Coding a PHP 7 Framework part 1" here.

Lectric is a PHP framework, tentatively defined as a CARV PHP framework(controller - action|response|view). It's basic pricipal is that most web apps are tools for viewing something, performing an action or generating a none-view response. Exactly what the framework does, generate a view, response or run an action is determined by the url - described as the URL Nodes. It follows PSR-2 coding standards and PSR-4 autloading standards. 

Installation

To install:

    • Unpack the git archive into your projects' root directory
    • Define the following (provided you need to) constants in /engine/app_config.php (create if needed):
      • DB_NAME - database name
      • DB_USER - database user
      • DB_PASSWORD - databse password
      • DB_HOST - database host (probably "localhost")
      • DEBUG - true or false (true displays all errors, false displays default ini errors), default to true
      • SESSION_IGNORES - flat array of /do/ directory files that require session to be *OFF*, defaults to []
      • DEFAULT_DIRECTORY - the directory under /view/ that Lectric looks for a render.php file, defaults to "default"
      • SITE_NAME - what's the application called? defaults to "Lectric"
      • SITE_LINK - the domain name, eg. foo.bar.com
      • SITE_DESCRIPTION - default description for website (useful for uncaught webapage meta descrips... - defaults to "Lectric Default Installation"
      Note: You can use logic here to define both dev and production DB settings, by testing on $_SERVER['HTTP_HOST'] and providing different definitions!
    • run install.sql to set up basic database tables
    • browse to / and read the messages displayed!

An example /engine/app_config.php file might be:

<?php

	/*
	* Set DB connection details
	*/
		if (strpos($_SERVER['HTTP_HOST'],'dev.url') !== false) {
			// DEV
			define('DB_NAME', 'dev_db');
			define('DB_USER', 'dev_user');
			define('DB_PASSWORD', 'devpass');
			define('DB_HOST', 'localhost');
			
			/*Error Reporting on, turn off after deployment. */
			define('DEBUG', TRUE);
		} else {
			// LIVE
			define('DB_NAME', 'live_db');
			define('DB_USER', 'live_user');
			define('DB_PASSWORD', 'livepass');
			define('DB_HOST', 'localhost');
			
			/*Error Reporting on, turn off after deployment. */
			define('DEBUG', FALSE);
		}


	/*
	* Timezone 
	*/
		date_default_timezone_set('Europe/London');
		
	/* 
	* core definitions
	*/
		define('SESSION_IGNORES', []);
		define('DEFAULT_DIRECTORY', 'public');
		define('SITE_NAME','Demo Website');
		define('SITE_LINK','site.url');
		define('SITE_DESCRIPTION','Some description about the Demo Website');

Basics

Adding classes - PSR-4

Classes should be added to the framework using the PSR-4 standard with 1 caveat - no sub namespaces. For example, to use the class \yourProjectNamespace\yourClass, you must create a file yourClass.class.php in /library/yourProjectNamespace/. Inside your class file, you must then obviously declare the namespace as yourProjectNamespace. Most of the time you will want to extend the \Lectric\lecPDO class. Fill your boots.

Working Directory

To start developing with Lectric after installation, it's as simple as cracking open the /view/default/ directory and modifying the files within!

It is recommended that a different default directory be used, by copying /view/default/ into another directory in /view/. Usually this would be /view/public/. This is to ensure that if you pull from this repo in the future, it doesn't overwrite any changes you've made to /view/default/. Ensure to define your default directory if not using /view/default/ in /engine/app_config.php - e.g. define('DEFAULT_DIRECTORY', 'public').

**A working directory can never be called /view/do/**

Adding Pages

To add webpages for use in development, add them to <working_directory>_views in your database. These will be available to view on the app provided the URL matches against it using the following rules:

  • The URL is split into nodes (see /library/Lectric/view.class.php) by the character "/"
  • The number of nodes and presence of a physical directory in /view/ determines:
    • The URL directory - the directory (if any) a user can see in the address bar - also the values stored in <FILE Directory>_directories
    • The FILE directory - the directory under /view/ to look for a render.php - also which directories and views table to look at, e.g. <FILE Directory>_directories and <FILE Directory>_views
    • The page URL - the end node of the URL - also the value in the <FILE Directory>_views table in the `url` field used to select the view
  • If browsing to /, the URL directory = "root" (see default_directories table), the page URL = "index" and the FILE directory = defined DEFAULT_DIRECTORY const
  • If there is only 1 URL Node:
    • If the node is a directory under /view/, then the URL directory = "root" (see default_directories table), the page URL = "index" and the FILE directory = node value (URL_NODES[0])
    • If the node is not a diurectory under /view/, then the URL directory = "root" (see default_directories table), the page URL = node value (URL_NODES[0]) and the FILE directory = defined DEFAULT_DIRECTORY const
  • If there are 2 or more URL nodes:
    • If the first node is a Directory under /view/:
      • If there are 3 or more URL nodes, then the URL directory = second node, the page URL = end node (end(URL_NODES)) and the FILE directory = first node value (URL_NODES[0])
      • If there are 2 URL nodes, then the URL directory = "root" (see default_directories table), the page URL = end node (end(URL_NODES)) and the FILE directory = first node value (URL_NODES[0])
    • If the first node is not a Directory under /view/, then the URL directory = first node value (URL_NODES[0]), the page URL = end node (end(URL_NODES)) and the FILE directory = defined DEFAULT_DIRECTORY const

Once a record has been made in the database, you'll need to have an appropriate file structure for the /view/DEFAULT_DIRECTORY/render.php file to call upon. As with the default repo, we recommend:

  • /view
    • /template
      • /common
        • /header.php etc..
      • /includes
        • view specific "chunks"
      • /views
        • index.php etc...
    • /img
    • /css
    • /js
    • /render.php

Following the Lectric sample default project, /view/default/render.php loads the view from the database and puts it in $view->page property, to be used in the following included template common files. By being in render.php, these files will be common to every view in the /view/default/ directory (unless you stipulate some logic in your render file). In /view/template/common/content.php (the second included common view file) you can see we're checking if a specific /view/template/views/*.php file exists by using the `url` field value from the loaded view. In this case, index.php does exist, so it is included. Inside /view/template/views/index.php you can see we use the `html` field value from the loaded view, plus some extra HTML directly in the view file. By adding view fields to your view tables, you can build as many insertions from the database as needed (for example, `sidebar_content`, `testimonial_snippet`). You may also want to include files from the /view/template/includes/ directory, through this is usually reserved for class html ouput functions.

Do-ing things

Everything in Lectric is either a "view", a "do-response" or a "do-action".

Views are simple, they are discreet generated webpages defined by the URL, and should be comprised of common elements (header, footer, etc), database driven elements (meta title etc) and includes (small bits of html that collect to make up the bulk of a view). See above.

Do Response
  • URL Format -  /do/response/<actionGroup>/<action>
  • Directory Format - /do/<folder>/<action>.php

A do-response is used to get anything back that isn't nothing, or a view. For example, an api script may return JSON headers and content, thus being a response. Response Do's reside in /do/<folder>/<action> and can be access from a browser by using the following URL format:/do/response/<actionGroup>/<action>, where actionGroup = a folder in /do/ appropriately named for the actions within it and <action> is the name of the php file within /do/<actionGroup>/ (without the .php).

For example, you might have an api that has two functions, returning data and returning meta-data. You might organise your do files into /do/api/data.php and /do/api/meta-data.php. To call these scripts, you would browse to /do/response/api/data (or meta-data). 

Inside a /do/<actionFolder>/<action> script file, you have access to all the constants setup in the config. This file is included under the /library/Lectric/controller.class.php construct function. 

Do response actions scripts also accept GET params, but must test for existence of GET / POST vars.

Do Action
  • URL Format - /do/action/<namespace>/<className>/<functionName>
  • Directory Format - /library/<namespace>/<className>.class.php

A do-action is a way to run a specific class function (inventively called a "do" function). These functions are called if the URL falls into the format of /do/action/<namespace>/<className>/<functionName>. You would run a do-action if you wanted to return a view or nothing only.

Classes that have to run do functions must:

  • accept lecDBH as the first argument for the construct (if the class extends \Lectric\SQLQueryPDO, this will be the case anyway. otherwise, make sure you set your additional argument defaults!)
  • reside in the folder asked for by the URL nodes

Do functions must:

  • be called do_<functionName>
  • be a public function
  • have a return type of \Lectric\controlAction and return said object

The \Lectric\controlAction is used to determine what happens once the do function has been run. The construct can be passed the arguments of type, param1, param2 or no arguements to simply exit. For example, if after calling the do_function, you want the user to be redirected to "/", and providing you have not set any other headers then return new \Lectric\controlAction('view', '/'), optionally passing back a message in param2 to be saved to the controller session messages (see controller dox for details).

The example default Lectric project has examples of both do-responses and do-actions. See /view/default/js/js_home.php for do-response call and /do/lectric/test.php for a form that posts to a do-action (see /library/Lectric/lecDefault.class.php too!).

Further reading

 All classes within Lectric have been docblocked, for you to generate documentation (I reccomend phpdox - it works fine with PHP 7.1.1 as of this release).