README

Paper Cello is a library of miscellaneous PHP functions. There are functions for datetimes, bcrypt hashing, clamping, pagination, routing and SHA1 token generation.

Documentation

All functions have a DocBlock. So you can read the source code or generate documentation with phpDocumentor.

Requirements

PHP 5.3 or greater

Source Code

The project is on GitHub. All the source code is in this file.

Tests

All tests are in the test directory. There is a test for each function; the name of the test script is the function name.

Installation

Install using composer:

{
    "require": {
        "paper-cello/paper-cello": "0.6.0",
    }
}

or you can install manually:

require 'paper-cello.php';

datetime_now() and datetime_to()

Use datetime_now() and datetime_to() to handle datetimes. These functions handle time zones and daylight saving time correctly without having to use any other time settings.

Get the current UTC datetime with datetime_now():

$utc_now = pc\datetime_now(); //2014-07-24 04:33:12

Use datetime_to() to convert a UTC datetime to a time zone and format:

echo pc\datetime_to($utc_now, 'America/Los_Angeles', 'M j, Y g:ia');

//Jul 23, 2014 9:33pm

bcrypt_hash()

Use bcrypt_hash() to hash passwords. Use either a cost value from 4-31:

$hash = pc\bcrypt_hash('password', 12);

//$2a$12$DMWzyZ.iU444JC/.270Bqe84eIwqHOD7ct4jkHY/0gaNv98fHNGx.

Or use a previously obtained hash:

echo pc\bcrypt_hash('password', $hash);

//$2a$12$DMWzyZ.iU444JC/.270Bqe84eIwqHOD7ct4jkHY/0gaNv98fHNGx.

clamp()

Clamp a value to a range:

echo implode(', ', array(
    pc\clamp(5, 1, 10),
    pc\clamp(0, 1, 10),
    pc\clamp(11, 1, 10),
    pc\clamp(11, 1, 10.4),
    pc\clamp('d', 'c', 'f'),
    pc\clamp('a', 'c', 'f'),
    pc\clamp('i', 'c', 'f')));

//5, 1, 10, 10.4, d, c, f

paginate()

Compute total number of pages and current page number given number of items, items per page and raw current page number:

$num_items = 24;
$items_per_page = 5;
$raw_current_page_num = 2;

var_dump(pc\paginate(
    $num_items,
    $items_per_page,
    $raw_current_page_num));

/*
array
  0 => int 5
  1 => int 2
*/

route()

Use route() to include one of many PHP scripts based on a value. These examples use echo; use require in your application.

Route on the default $_GET['r']:

echo pc\route(array(
    null => 'home.php',
    'contact' => 'contact.php'));

//home.php

Use a base directory:

echo 'my/route/' . pc\route(array(
    null => 'home.php',
    'contact' => 'contact.php'));

//my/route/home.php

Route on a POST value:

echo pc\route(
    array(
        null => 'one.php',
        'two' => 'two.php'),
    $_POST['r']);

//one.php

Route on a value for testing:

echo pc\route(
    array(
        null => 'home.php',
        'chess' => 'chess.php',
        'golf' => 'golf.php'),
    'golf');

//golf.php

There is a shortcut so you don't have to specify keys in the array. For example the below is equivalent to the above:

echo pc\route(
    array(
        null => 'home.php',
        'chess.php',
        'golf.php'),
    'golf');

//golf.php

sha1_token()

Get a random token:

echo pc\sha1_token(); //003046aec403e654eaadad31658bcad04ad7f95c

LICENSE

MIT http://ryf.mit-license.org/