README

The lightweight core of SPF (Si's PHP Framework). Provides error and exception handling and commonly used helper functions.

Requirements

This library requires only PHP 7.2 or later and the SPF Contracts package (simon-downes/spf-contracts).

Installation

It is installable and autoloadable via Composer as simon-downes/spf-core.

Alternatively, download a release or clone this repository, and add the \spf namespace to an autoloader.

License

SPF Core is open-sourced software licensed under the MIT license. See LICENSE.md for details.

Quick Start

SPF Core provides a basic exception and error handling wrapper for blocks of code, be they command-line scripts, complete web apps or simple functions.

Running code with SPF is a simple as calling the static run() method with a callable parameter.

use spf\SPF;

// Using a closure
SPF::run(function() {
  echo "Hello World";
});

// Using a function name
function hello() {
  echo "Hello World";
}
SPF::run('hello');

// Using an object...
class Foo {
  public static function hello() {
    echo "Hello World";
  }
  public function helloWorld() {
    echo "Hello World";
  }
  public function __invoke() {
    $this->helloWorld();
  }
}

// ...static callback
SPF::run(['Foo', 'hello']);

// ...instance callback
$o = new Foo();
SPF::run([$o, 'helloWorld']);

// ...invokable object
SPF::run($o);

Error and Exception Handling

SPF Core provides default error and exception handlers:

Errors are converted to ErrorExceptions and passed to the exception handler if the error matches the current error_reporting level.
Exceptions are handled by the specified exception handler or a default one if none is specified.

You can specify a custom exception handler by passing a callable to the appropriate method:

use spf\SPF;

SPF::setExceptionHandler($callback);

Debug Flag

SPF provides a debug flag accessible via:

use spf\SPF;

// enable/disable debug flag
SPF::setDebug(true);

// Return current setting of debug flag
SPF::isDebug();

Usage of the debug flag is left almost entirely to clients. The only uses within the framework are:

to determine whether to display a detailed error page (if debug flag is set) or a simple static error page
calls to the d() and dd() dump functions are ignored if the debug flag is not set

The default simple static error page can be overriden: by passing the path and file name to the ```

use spf\SPF;

SPF::setErrorPage($path_to_file);

Variable Dumping

SPF provides an enhanced var_dump() implementation that can output detailed variable information in plain text.

use spf\SPF;

SPF:dump($var);

SPF also defines two shortcut functions for accessing the variable dumping functionality:

d() - calls SPF::dump() for each passed argument
dd() - same as d() but will call die() once the arguments have been dumped

These shortcut methods do nothing if the debug flag is not set.

Helpers

SPF provides a variety of helper functions and more can be easily added. Helper functions are implemented as static class methods and registered either by passing the class name to the SPF::registerHelper() method (registers all public static methods) or by passing a class and method name to the SPF::addHelperMethod() (registers a single method). Once registered helper functions can be called via static method call to SPF.

use spf\SPF;

class MyHelper {
  public static function foo() {
    echo 'foo';
  }
  public static function bar() {
    echo 'bar';
  }
}

SPF::registerHelper('\\MyHelper');

SPF::foo();
SPF::bar();

General Helpers

isCLI() - determines if the script is running in a CLI environment

Array Helpers

uniqueIntegers() - return an array of unique integers
isTraversable() - determines if a variable can be interated over using foreach
isAssoc() - determine if an array is associative or not
filterObjects() - filter an array to instances of a specific class
get() - return an item from an array or object or a default value if the item doesn't exist
getNullItems() - filter an array to items that are null
pluck() - extract a single field from an array of arrays of objects
sum() - calculate the sum of the specified item from an array of arrays or objects
min() - calculate the min of the specified item from an array of arrays or objects
max() - calculate the max of the specified item from an array of arrays or objects
implodeAssoc() - implode an associative array into an array of key/value pairs
makeComparer() - create a comparison function for sorting multi-dimensional arrays

Date/Time Helpers

makeTimestamp - convert a value into a timestamp
seconds() - convert a string representation containing one or more of hours, minutes and seconds into a total number of seconds

String Helpers

parseURL() - parse a url into an array of it's components
randomHex() - generate a random hex string of a specific length
randomString() - generate a random string of a specific length
uncamelise() - convert a camel-cased string to lower case with underscores
slugify() - convert a string into a form suitable for urls
removeAccents() - convert accented characters to their regular counterparts
latin1() - convert a UTF-8 string into Latin1 (ISO-8859-1)
utf8() - convert a Latin1 (ISO-8859-1) into UTF-8
ordinal() - return the ordinal suffix (st, nd, rd, th) of a number
sizeFormat() - convert a number of bytes to a human-friendly string using the largest suitable unit
xssClean() - remove XSS vulnerabilities from a string
stripControlChars() - remove control characters from a string

Inflection Helpers

pluralise() - Determine the plural form of a word (English only)
singularise() - Determine the single form of a word (English only)

simon-downes / spf-core

Maintainers

Details