Humblee

A humble PHP framework & CMS

Additional Humblee Functionality

Database Querying With Idiorm

Humblee relies on the Idiorm Object-Relational Mapper for querying the database. While you can, off course, write your own database connection code, Idiorm provides a simple and fluent query builder which is recommended. It is fully documented at https://idiorm.readthedocs.io/en/latest/querying.html

Core::getURIparts()

Returns array off URL request structure. For example, if the page called is my-site.tld/Locations/Connecticut/Enfield

print_r( Core::getURIparts() );
// returns
Array( 
 [0] => Locations
 [1] => Connecticut
 [2] => Enfield
)

Core::forward()

Forward the user to another page on the site using Output Buffering. You can also optionally pass a status code.

<?php
Core::forward('Locations'); // forwards to ~/Locations
Core::forward('Locations/Connecticut'); // forwards to ~/Locations/Connecticut
Core::forward('Locations', '301 Moved Permanently'); // forwards to ~/Locations with "HTTP/1.1 301 Moved Permanently" header.

CSRF and HMAC

To mitigate Cross-site Request Forgery (CSRF), all requests passing data to server should use $_POST rather than $_GET. Furthmore, Humblee can generate a unique CSRF token that is saved in the user's session. By including this token in a hidden form field being submitted, the processing script on the server side can be assured that the user did not unintentionally make a request.

<?php
$crypto = new Core_Model_Crypto;
$csrf_token = $crypto->getCsrfToken();
?>
<form method="post">
 <input type="hidden" name="csrf_token" value="<?php echo $csrf_token ?>">
 <input type="text" name="transfer_funds" value="0.00">
 <input type="submit" value="submit">
</form>
....
<?php
 //on postback
 if($_POST['csrf_token'] != $_SESSION[session_key]['csrf_token']) die "invalid request";

The preferred CSRF mitigation technique of Humblee is to use a Hashed Machine Authentication Code (HMAC). Humblee can create a unique random string for each page load, then also hash it using the CSRF token as a salt.

<form method="post">
 <?php 
    $crypto = new Core_Model_Crypto;
    $hmac_pair = $crypto->get_hmac_pair(); 
  ?>
 <input type="hidden" name="hmac_token" value="<?php echo $hmac_pair['message'] ?>">
 <input type="hidden" name="hmac_key" value="<?php echo $hmac_pair['hmac'] ?>">
 <input type="text" name="transfer_funds" value="0.00">
 <input type="submit" value="submit">
</form>
...
<?php
//on postback
$crypto = new Core_Model_Crypto;
if(!$crypto->check_hmac_pair($_POST['hmac_token'], $_POST['hmac_key'])) die "Invalid Machine Authentication Key";

Encryption

If you are running PHP >= 7.2 Humblee will use the integrated Sodium cryptography library for encrypting and decrypting. In older PHP, the libsodium should have been installed via composer.

When encrypting text, it is important to note that the returned variable is an array containing both the encrypted string AND a unique nonce token that is required to decrypt the string. This value must be retained to "unlock" the file.

<?php 
$plain_text = "My plain text string";
$crypto = new Core_Model_Crypto;

$encrypt = $crypto->encrypt($file_content);
echo $encrypt['crypttext'];

$decrypt = $crypto->decrypt($encrypt['crypttext'], $encrypt['nonce']);
echo $decrypt;

CRUD Tool

Humblee has a built in tool for easily processing your forms that Create, Read, Update and Delete rows from a given database table at ~/humblee/models/tools.php. Passing the table name and path to your form will output your form, passing the data for a given database row. Including a $_POST array of submitted form fields will create or update that row in the database.

<?php
$params = array("id"=> (isset($this->_uri_parts[2])) ? $this->_uri_parts[2] : false,
                        "table"=> "my_data_table,
                        "view" => _app_server_path .'humblee/views/admin/my-crud-editor.php', 
                        "post" => (isset($_POST) && count($_POST) > 0) ? $_POST : false,
                        "allow_html" =>true
                        );
var $tools = new Core_Model_Tools;
$tools->CRUD($params);

Both the "Manage Templates" and "Manage Content Blocks" utilize this functionality. To see these forms using the CRUD method, review their respective functions in ~/humblee/controller/admin.php

Send Email

When generating email messages from the system, you can call $tools->sendEmail() to create an send the e-mail. If you optionally pass $_POST data, such as from a user submitted contact form, the sendEmail method will generate the appropriate HTML and add the information to the e-mail.

If you have enabled Mailgun by adding the appropriate credentials to your configuration environment, Humblee will send the mail via Mailgun's API. Otherwise, the message will be sent using PHP's mail() function. If you have not configured mailgun, make sure your server is setup to send mail.

Humblee also includes a method for creating e-mail templates. The template used for Humblee generated transactional emails, such as password recovery, can be found at ~/humblee/views/email/notification.php. You can modify this template as need and also create your templates for your own application. To use a template, you can call $tools->emailTemplate() and pass the subject, message and path to your template's view.

$subject = "Welcome to my great website";
$body = "Thank you for signing up for my newsletter";
$to = $_POST['validated_and_cleaned_user_email_address'];
$from = $_ENV['config']['default_email'];
$tools = new Core_Model_Tools;

// inject message into a template
$message = $tools->emailTemplate($subject, $body, _app_server_path . 'humblee/views/email/notification.php');

// send the e-mail
$tools->sendEmail($to,$from,$subject,$message);

Send SMS messages

Text messages can be sent from the system if you have enabled Twilio by adding the appropriate credentials to your configuration environment and installed the Twilio SDK via composer.

<?php
$to = '860-265-1217';
$message = "Thank you signing up for text message notifications";
$tools = new Core_Model_Tools;
$tools->sendSMS($to,$message);

For more robust SMS implementations, such as sending images or handling responses, see the Twilio documentation and then create a Twilio client object by initiating the library with your stored credentials:

$client = new Twilio\Rest\Client($_ENV['config']['TWILIO_AccountSid'],$_ENV['config']['TWILIO_AuthToken']);