botk/context

ini file management, sanitization, validation

WARNING

The support to this project is now discontinued. Update your links., _(*1)

Find the old version as tagged branch., _(*2)

BOTK\Context

, _(*3)

Ultraligth validation and sanitization helpers., _(*4)

This is a BOTK package. Please refer to http://ontology.it/tools/botk for more info about BOTK project., _(*5)

Quick start

The package is available on Packagist. You can install it using Composer., _(*6)

composer require botk/context

Some code examples in samples directory., _(*7)

BOTK\Context package documentation

Abstract

This package exports a set of class to manage the context of a RESTful request., _(*8)

A Context is defined as the full set of variables available runtime durin the serving of an http request. Variables are grouped in distinct name spaces., _(*9)

All variables in name spaces are read only., _(*10)

This package exposes the methods to sanitize and validate context variables., _(*11)

Note that cookies and session aren't part of context. This because proper RESTful resource implementation shouldn't need persisten status in any way., _(*12)

Installation

This package follows BOTK guide line for installation and require composer., _(*13)

Add following dependances to composer.json file in your project root:, _(*14)

{
    "require": {
        "botk/context": "*"
    }
}

The Context class

A Context is the full set of all that a CGI endpoint knows about  Request beside its URI. Context space contains system environment variables, requests header, request body, server specific vars, cookies, variables in configuration files, local define variables, etc etc.., _(*15)

Context variables are grouped in namespaces.BOTK\Context\Context class provide the method  ns(<var>namespace name</var>) to access name spaces. There are five predefined namespaces:, _(*16)

1. the variables defined in the heading of the request and exposed by web server (INPUT_SERVER);
2. the variables encoded in http URI (INPUT_GET);
3. the variables encoded in http body (INPUT_POST);
4. the system environment (INPUT_ENV);
5. local defined variables (Context::LOCAL).

Beside these, Context class allow you to define dynamic namespace built from .ini files loaded runtime from a configuration directory. The name of the namespace is the name of the configuration file without .ini extension., _(*17)

The configuration file must exists when is first referenced. The default configuration directory is ../configs, that normally is a directory placed at the same level of the directory that contains the scripts who instance a context class. You can change the default directory defining the environment variable $_ENV['BOTK_CONFIGDIR']., _(*18)

Context shold be considered as a readonly data structure because you cant change the resource execution context., _(*19)

For example suppose to have a end-point script is in myapp/httdocs/index.php so, to get a success on following code, it must exist myapp/configs/sample.ini file:, _(*20)

use BOTK\Context\Context as CX;
$sampleNameSpace = CX::factory()->ns('sample');

If you want to put the .ini file in the same end-point directory:, _(*21)

use BOTK\Context\Context as CX;
$_ENV['BOTK_CONFIGDIR'] = '.';
$sampleNameSpace = CX::factory()->ns('sample');

You can also access to local variable passing them to context constructor:, _(*22)

$myvar = 'ok'; // define a variable in local scope
$v = CX::factory(get_defined_vars())->ns(CX::LOCAL)->getValue('myvar');
//$v == 'ok'

Context class exposes the method guessRequestCanonicalUri() that returns the current request uri in canonical form and the method guessRequestRelativelUri() that returns it as relative path., _(*23)

Please note that get request uri is not a trivial job, this because http servers and proxyes can change what the user entered. You can just guess about it., _(*24)

The ContextNameSpace Class

This class implements the controlled access to set of variables., _(*25)

The getValue() method

The BOTK\Context\ContextNameSpace class exports the method getValue() that allows to validate and sanitize variables defined in a namespace (see PHP Validation & Sanitization article)., _(*26)

If somethings goes wrong it throwns an error that can be trapped by standard BOTK error management., _(*27)

getValue() exposes following interface:, _(*28)

In addition to getValue()``ContextNameSpace class expose a set of shortcuts for easy to read and write code., _(*29)

validator shortcucts

Some validators shold be boring to write, here are a set of predefined shortcuts:, _(*30)

getValue shortcucts

Even with validator shortcuts, a call to getValue method can be too verbose, here are some shortcut you can use for common task:, _(*31)

• getString($varName,$default = null):  same as getValue($varName,$default, null, FILTER_SANITIZE_STRING);
• getURI($varName,$default = null):  same as getValue($varName,$default, self::STRING('/.+/'), FILTER_SANITIZE_URL)

PagedResourceContext class

The PagedResource class is a facility to manage the context of a resource whose query string can contains variables to drive pagination processing. It is a specialization of Context class and like Context should be considered as a read-only data structure., _(*32)

The resource paging context is inspired on W3C's Linked Data Platform Paging specifications .Here are some imported definitions:, _(*33)

Paged resource

A resource  whose representation may be too large to fit in a single HTTP response, for which a server offers a sequence of single-page resources. A paged P is broken into a sequence of pages (single-page resources) P₁, P₂, ...,P_n, the representation of each P_i contains a subset of  P..

Single-page resource

One of a sequence of related resources P₁, P₂, ...,P_n, each of which contains a subset of the state of another resource P. P is called the paged resource. For readers familiar with paged feeds, a single-page resource is similar to a feed document and the same coherency/completeness considerations apply. Note: the choice of terms was designed to help authors and readers clearly differentiate between the _resource being paged_, and the _individual page resources_, in cases where both are mentioned in close proximity.

first page

The uri to the first single-page resource of a paged resourceP. For example http://www.example.org/bigresource?page=0

next page

The uri  to the next single-page resource of a paged resourceP.

last page

The uri  to the last single-page resource of a paged resourceP.

previous page

The uri  to the previous single-page resource of a paged resourceP.

Pagination require some variable to be specified in resource URI query strings. Such variables name and other default values can be passed to class constructor as an option associative array. Here are supported keywords:, _(*34)

• plabel : contains the variable that contains page num. For default 'page'
• pslabel  : contains the variable that contains page size. For default 'pagesize
• pagesize  : contains the default value for page size. The default is 100

It exposes following methods:, _(*35)

`getSinglePageResourceUri( $pagenum = null, $pagesize=null)`

returns the canonical uri with page variables in query string. Without arguments returns current page resource uri

`getPagedResourceUri()`

return the resource uri wit page variables removed from query string 

`isPagedResource()`

returns true is resource uri contains page info

`getPageNum()`

returns the current page num

`getPageSize()`

returns the size of the page

`firstPageUri()`

returns the Resource uri for first Single page resource

`nextPageUri()`

returns the Resource uri for next page resource or the current page resource uri

`prevPageUri()`

returns the Resource uri for next page resource or the first page resource uri

`hasNextPage()`

returns true if a next page is available. By default returns true. It can be affected by `declareActualPageSize()` method

`isLastPage()`

returns true if the current is the last page. By default returns false. It can be affected by `declareActualPageSize()` method

`declareActualPageSize($count)`

inform context of the number of item in current Page, by default is 0\. This affects `hasNextPage()` and `isLastPageMethods()`.

Here is how declaretActualPageSize() affects hasNextPage() and isLastPage():, _(*36)

License

Copyright © 2016 by Enrico Fagnoni at LinkedData.Center®, _(*37)

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:, _(*38)

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software., _(*39)

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE., _(*40)