Introduction

OhCrud is a PHP micro framework that helps you quickly write simple yet powerful applications and create APIs. At its core, it provides the basic Create Read Update Delete methods to interact with MySQL or SQLITE.

Ninety percent of everything is crud.

Theodore Sturgeon

OhCrud uses composer and fully supports PSR-4 autoloading so you can reference your classes using the name spaces, You can easily define API or HTML endpoints and map incomming requests to your classes to handle, or you can use a catch all OHCRUD_DEFAULT_PATH_HANDLER to catch all the other requests.

Framework comes with a secure users and permissions handling, you can define per method permissions for all your API endpoints.

OhCrud uses Monolog liberary to handle logs, all PDO exceptions are automatically logged into the designated log file in a well formated way.

While I belive any programming language that comes with fulctions like money_format, or ucwords and so on... right out of the box is CRUD, my goal is to make things less shitty with my framework, but as a rule still contains ninety percent crud!

Getting Started

The OhCrud framework has a few system requirements and you can run it on a Raspberry Pi 1 with SQLITE database, you will need to make sure your server meets the following requirements:

• PHP >= 5.6.0 (PHP 7 Recommended)
• PDO PHP Extension
• Mbstring PHP Extension
• PHP Curl Extension
• PHP SQLITE 3 (if using SQLITE for your database)

Installation

OhCrud utilizes Composer to manage its dependencies. So, before using OhCrud, make sure you have Composer installed on your machine.

To install OhCrud, first create a directory for your project in your webserver's root directory:

mkdir /var/www/OhCrud

Then run the following commands:

git clone https://github.com/fellowgeek/OhCrud.git /var/www/OhCrud
rm -rf /var/www/OhCrud/.git
composer update
composer dump-autoload

After all the files are copied in place you need to configure your webserver to redirect all the traffic from the missing paths to go to index.php, you can achieve this for Apache and Nginx using the configuration below:

Apache configuration

Make sure apache has the mod_rewrite enabled, there is a .htaccess file included in OhCrud package that should take care of everything for you but if you need to make one make sure it looks like this:

<IfModule mod_rewrite.c>
	RewriteEngine On
	RewriteBase /
	RewriteCond %{REQUEST_FILENAME} !-f
	RewriteCond %{REQUEST_FILENAME} !-d
	RewriteRule ^.+$ index.php [QSA,L]

	RewriteRule ^/?logs/app\.log$ - [F,L]
	RewriteRule ^/?assets/db/data\.db$ - [F,L]
</IfModule>

Make sure your Apache virtual host is configured with the AllowOverride option so that the .htaccess rewrite rules can be used:

AllowOverride All

Nginx configuration

This is an example Nginx virtual host configuration for the domain example.com. It listens for inbound HTTP connections on port 80.

You should update the server_name, error_log, access_log, and root directives with your own values. The root directive is the path to your application’s root directory.

server {
    listen 80;
    index index.php index.html index.htm;
    error_log /path/to/example.error.log;
    access_log /path/to/example.access.log;
    root /path/to/ohcrud;
    server_name example.com;

    location / {
	try_files $uri $uri/ @rewrite;
    }

    location @rewrite {
        rewrite ^.+$ /index.php;
    }

    location ~ \.php$ {
        include snippets/fastcgi-php.conf;
        fastcgi_pass unix:/run/php/php7.0-fpm.sock;
    }

    location ~ /\.ht {
        deny all;
    }

    location ~ /(logs|assets/db) {
	deny all;
    }
}

Configuration

Use the table below to define the following settings constants in the settings.php file that should be placed at the application's root directory. A settings.sample.php file is provided as a starting point.

Directory Structure

OhCrud utilizes Composer to manage its dependencies, all classes should be PSR-4 compliant to work with autoloading.

Below you can see a breakdown of the OhCrud folders in alphabetical order.

The Basics

All OhCrud classes inherit from the Core class. Ideally all of your models and controllers should do the same. If a class needs databse functions should inherit from the DB class, which itself inherits from Core.

API and WEB endpoints are handled by the Router class, the Router checks if user has the correct permissions to access the end point and Routes the request to the correct class to handle.

OhCrud uses the Users class to authenticate users and check permissions, when OHCRUD_DEBUG_MODE set to TRUE if the Users table does not exists, OhCrud will auto create the table and insert a default admin user into it.

OhCrud default username and password

Username : admin
Password : admin

Core Object

Every class in OhCrud inherits from the Core object, This class is responsible for setting the output type and http headers and performing tasks like logging, errors handling, remote requests, and debug.

Properties

Methods

All the methods in Core can be used in a chain, see the example below:

$this->log('info', 'This is a test log.')->debug($_SERVER)->request('https://www.reddit.com/r/cats/.json')->debug();

Database Object

DB object is in charge of all the CRUD (Create Read Update Delete) work. This class inherits from Core, and comes with all the properties and methods that Core has.

Properties

Same as Core object

Methods

Same as Core object plus the following:

$this->run(
	'SELECT * FROM Users Where ID=:ID',
	[
		':ID' => 1
	]
);

$this->create(
	'Users',
	[
		'USERNAME' => 'admin',
		'PASSWORD' => password_hash(
			'admin', PASSWORD_BCRYPT, [
				'salt' => __OHCRUD_SECRET__,
				'cost' => 10
				]
			),
		'FIRSTNAME' => 'admin',
		'LASTNAME' => 'admin',
		'GROUP' => 1,
		'PERMISSIONS' => 1,
		'STATUS' => 1
	]
);

$this->read(
	'Users',
	'ID=:ID',
	[
		':ID' => 1,
	],
	'ID, USERNAME, FIRSTNAME, LASTNAME'
);

$this->update(
	'Users',
	[
		'FIRSTNAME' => 'JOE',
		'LASTNAME' => 'COOl'
	],
	'ID=:ID',
	[
		':ID' => 1,
	]
);

$this->delete(
	"Users",
	"ID=:ID",
	[
		':ID' => 1,
	]
);

$this->run('SELECT * FROM Users')->first();

Router Object

Router object is your interface to the outside world, it will take a path which can be a URI or a console argument and will call upon the appropriate class and method to handle the request.

To accomplish this task Router will look at the OHCRUD_ENDPOINTS and will call the class and method based on the defined name space, if the path was not defined in OHCRUD_ENDPOINTS then Router will look at OHCRUD_DEFAULT_PATH_HANDLER and will route the request to the defaultPathHandler method of the class defined here.

If Router fails to find a path after trying the steps above, it will return a 404 error.

Becasue router is matching paths to namespaces, it is very fast and you can change your endpoints at any time or redirect them to new namespaces to handle, this will make rolling out new versions of APIs super easy.

Permissions

Before calling objects and methods Router checks the target class for the public $permissions array property.

namespace app\models;

class Example extends \OhCrud\DB {

    public $permissions = [
        'object' => __OHCRUD_PERMISSION_ALL__,
        'exampleMethodA' => 2,
        'exampleMethodB' => 7
    ];
/*
the rest of the code for the Example class goes here...
*/
}

If a user is present in the $_SESSION, Router will check that users PERMISSIONS value against the number assigned to the target method in $permissions array. if user's PERMISSIONS value smaller than or equal to the methods value it will grant access otherwise will return a 403 error.

the 'object' key in the $permissions array controls the global access to the object.

To grant full access to a method or object without requiring user to login use OHCRUD_PERMISSION_ALL constant.

When accessing a protected method, if user is not logged in, OhCrud will ask for the login credentians via basic authentication.

Users Object

Users object is the OhCrud's way of handling users and permissions, if OHCRUD_DEBUG_MODE is set to TRUE, OhCrud will create a Users table and will insert a defualt admin user into it as the starting point.

OhCrud default username and password

Username : admin
Password : admin

Properties

Same as DB object

Methods

Same as DB object plus the following:

Errors & Logging

OhCrud objects inherit from Core object, which means they all have a error($message, $outputStatusCode = 500) and log($level = 'debug', $message, array $context = array()) method. Use this method to throw errors and set the HTTP status code.

Database object (DB) will call the error method when a PDO exception occurs.

OhCrud uses Monolog liberary to handle logs, the log method in Core is a wrapper for Monolog. Use this method to record PSR-3 compliant log messages. The error method will also record a log.

In OhCrud logs are fomatted like the examples below (output is trimmed to fit in this documentation page) :

[2017-07-25 15:01:16] OHCRUD.WARNING:
Login attempt was not successful
{"ID":"1","USERNAME":"admin","FIRSTNAME":"admin","LASTNAME":"admin","GROUP":"1",...
----------------------------------------
[2017-07-25 15:21:33] OHCRUD.ERROR:
SQLSTATE[HY000]: General error: 1 no such table: SomeTable
[{"file":"/var/www/ohcrud/ohcrud/DB.php","line":74,"function":"error","class":"O...
----------------------------------------
[2017-07-25 15:37:09] OHCRUD.ERROR:
I'm sorry Dave, I'm afraid I can't do that.
[{"file":"/var/www/ohcrud/ohcrud/Router.php","line":141,"function":"error","clas...
----------------------------------------

Command Line Interface

You can call OhCrud paths and endpoints from your server's command line. When calling an endpoint from command line OhCrud will bypass the permissions array completely. If the otput type is not defined, OhCrud will print a debug output in the console. See example output below:

php path_to/index.php "/endpont/example/"