Skip to content

Configuration

Overview

There are two ways to apply settings to the Skinny application. First during Skinny application instantiation and second after instantiation. All settings can be applied at instantiation time by passing Skinny’s constructor an associative array. All settings can be retrieved and modified after instantiation, however some of them cannot be done simply by using the config application instance method. These exceptions will be noted below. Before available settings are listed, here's a quick explanation of how you may define and inspect settings with your Skinny application.

During Instantiation

To define settings upon instantiation, pass an associative array into the Skinny constructor.

<?php
$settings = ['debug' => true];
$app = \Skinny\Skinny::newInstance($settings);

After Instantiation

To define settings after instantiation, most of them can use the application instance config() method; the first argument is the setting name and the second argument is the setting value.

<?php
$app->config('debug', false);

You may also define multiple settings at once using an associative array:

<?php
$app->config([
    'debug' => true,
    'templates.path' => '../templates',
]);

The config() method also retrieves a setting's value; however, you only pass one argument — the name of the setting you wish to inspect. If the setting you request does not exist, null is returned.

<?php
$settingValue = $app->config('templates.path'); //returns "../templates"

You are not limited to the settings shown below; you may also define your own.

Settings

mode

This is an identifier for the application’s current mode of operation. The mode does not affect a Skinny application’s internal functionality. Instead, the mode is only for you to optionally invoke your own code for a given mode with the configureMode() application method.

The application mode is declared during instantiation, either as an environment variable or as an argument to the Skinny application constructor. It cannot be changed afterward. The mode may be anything you want — “development”, “test”, and “production” are typical, but you are free to use anything you want (e.g. “foo”).

<?php
$app = \Skinny\Skinny::newInstance(array(
    'mode' => 'testing'
));
Data Type
string
Default Value
“development”

debug

Heads Up! Skinny converts errors into ErrorException instances.

If debugging is enabled, Skinny will use its built-in error handler to display diagnostic information for uncaught Exceptions. If debugging is disabled, Skinny will instead invoke your custom error handler, passing it the otherwise uncaught Exception as its first and only argument.

<?php
$app = \Skinny\Skinny::newInstance(array(
    'debug' => true
));
Data Type
boolean
Default Value
true

log.writer

Use a custom log writer to direct logged messages to the appropriate output destination. By default, Skinny’s logger will write logged messages to STDERR. If you use a custom log writer, it must implement this interface:

public write(mixed $message, int $level);

The write() method is responsible for sending the logged message (not necessarily a string) to the appropriate output destination (e.g. a text file, a database, or a remote web service).

To specify a custom log writer after instantiation you must access Skinny’s logger directly and use its setWriter() method:

<?php
// During instantiation
$app = \Skinny\Skinny::newInstance(array(
    'log.writer' => new \My\LogWriter()
));

// After instantiation
$log = $app->getLog();
$log->setWriter(new \My\LogWriter());
Data Type
mixed
Default Value
\Skinny\LogWriter

log.level

Heads Up! Use the constants defined in \Skinny\Log instead of integers.

Skinny has these log levels:

  • \Skinny\Log::EMERGENCY
  • \Skinny\Log::ALERT
  • \Skinny\Log::CRITICAL
  • \Skinny\Log::ERROR
  • \Skinny\Log::WARN
  • \Skinny\Log::NOTICE
  • \Skinny\Log::INFO
  • \Skinny\Log::DEBUG

The log.level application setting determines which logged messages will be honored and which will be ignored. For example, if the log.level setting is \Skinny\Log::INFO, debug messages will be ignored while info, warn, error, and fatal messages will be logged.

To change this setting after instantiation you must access Skinny’s logger directly and use its setLevel() method.

<?php
// During instantiation
$app = \Skinny\Skinny::newInstance(array(
    'log.level' => \Skinny\Log::DEBUG
));

// After instantiation
$log = $app->getLog();
$log->setLevel(\Skinny\Log::WARN);
Data Type
integer
Default Value
\Skinny\Log::DEBUG

log.enabled

This enables or disables Skinny’s logger. To change this setting after instantiation you need to access Skinny’s logger directly and use its setEnabled() method.

<?php
// During instantiation
$app = \Skinny\Skinny::newInstance(array(
    'log.enabled' => true
));

// After instantiation
$log = $app->getLog();
$log->setEnabled(true);
Data Type
boolean
Default Value
true

templates.path

The relative or absolute path to the filesystem directory that contains your Skinny application’s template files. This path is referenced by the Skinny application’s View to fetch and render templates.

To change this setting after instantiation you need to access Skinny’s view directly and use its setTemplatesDirectory() method.

<?php
// During instantiation
$app = \Skinny\Skinny::newInstance(array(
    'templates.path' => './templates'
));

// After instantiation
$view = $app->view();
$view->setTemplatesDirectory('./templates');
Data Type
string
Default Value
”./templates”

view

The View class or instance used by the Skinny application. To change this setting after instantiation you need to use the Skinny application’s view() method.

<?php
// During instantiation
$app = \Skinny\Skinny::newInstance(array(
    'view' => new \My\View()
));

// After instantiation
$app->view(new \My\View());
Data Type
string \Skinny\View
Default Value
\Skinny\View

cookies.encrypt

Determines if the Skinny app should encrypt its HTTP cookies.

<?php
$app = \Skinny\Skinny::newInstance(array(
    'cookies.encrypt' => true
));
Data Type
boolean
Default Value
false

cookies.lifetime

Determines the lifetime of HTTP cookies created by the Skinny application. If this is an integer, it must be a valid UNIX timestamp at which the cookie expires. If this is a string, it is parsed by the strtotime() function to extrapolate a valid UNIX timestamp at which the cookie expires.

<?php
// During instantiation
$app = \Skinny\Skinny::newInstance(array(
    'cookies.lifetime' => '20 minutes'
));

// After instantiation
$app->config('cookies.lifetime', '20 minutes');
Data Type
integer string
Default Value
“20 minutes”

cookies.path

Determines the default HTTP cookie path if none is specified when invoking the Skinny application’s setCookie() or setEncryptedCookie() methods.

<?php
// During instantiation
$app = \Skinny\Skinny::newInstance(array(
    'cookies.path' => '/'
));

// After instantiation
$app->config('cookies.path', '/');
Data Type
string
Default Value
”/”

cookies.domain

Determines the default HTTP cookie domain if none specified when invoking the Skinny application’s setCookie() or setEncryptedCookie() methods.

<?php
// During instantiation
$app = \Skinny\Skinny::newInstance(array(
    'cookies.domain' => 'domain.com'
));

// After instantiation
$app->config('cookies.domain', 'domain.com');
Data Type
string
Default Value
null

cookies.secure

Determines whether or not cookies are delivered only via HTTPS. You may override this setting when invoking the Skinny application’s setCookie() or setEncryptedCookie() methods.

<?php
// During instantiation
$app = \Skinny\Skinny::newInstance(array(
    'cookies.secure' => false
));

// After instantiation
$app->config('cookies.secure', false);
Data Type
boolean
Default Value
false

cookies.httponly

Determines whether cookies should be accessible through client side scripts (false = accessible). You may override this setting when invoking the Skinny application’s setCookie() or setEncryptedCookie() methods.

<?php
// During instantiation
$app = \Skinny\Skinny::newInstance(array(
    'cookies.httponly' => false
));

// After instantiation
$app->config('cookies.httponly', false);
Data Type
boolean
Default Value
false

cookies.secret_key

The secret key used for cookie encryption. You should change this setting if you use encrypted HTTP cookies in your Skinny application.

<?php
// During instantiation
$app = \Skinny\Skinny::newInstance(array(
    'cookies.secret_key' => 'secret'
));

// After instantiation
$app->config('cookies.secret_key', 'secret');
Data Type
string
Default Value
“CHANGE_ME”

cookies.cipher

The openssl cipher used for HTTP cookie encryption. Some supported ciphers may not be available on your platform:

  • camellia-256-ctr
  • camellia-256-cbc
  • aes-256-ctr
  • aes-256-cbc
  • camellia-128-ctr
  • camellia-128-cbc
  • aes-128-ctr
  • aes-128-cbc
  • cast5-cbc
  • bf-cbc
<?php
// During instantiation
$app = \Skinny\Skinny::newInstance(array(
    'cookies.cipher' => 'aes-256-cbc'
));

// After instantiation
$app->config('cookies.cipher', 'aes-256-cbc');
Data Type
string
Default Value
'aes-256-cbc'

http.version

By default, Skinny returns an HTTP/1.1 response to the client. Use this setting if you need to return an HTTP/1.0 response. This is useful if you use PHPFog or an nginx server configuration where you communicate with backend proxies rather than directly with the HTTP client.

<?php
// During instantiation
$app = \Skinny\Skinny::newInstance(array(
    'http.version' => '1.1'
));

// After instantiation
$app->config('http.version', '1.1');
Data Type
string
Default Value
“1.1”

routes.case_sensitive

Configure route patterns to be matched in a case-sensitive manner if true. This option must be set prior to Skinny's run() method.

// During instantiation
$app = \Skinny\Skinny::newInstance(array(
    'routes.case_sensitive' => true
));

// After instantiation
$app->config('routes.case_sensitive', false);
Data Type
boolean
Default Value
true

middleware.flash

Enaable/disable Flash middleware.

// During instantiation
$app = \Skinny\Skinny::newInstance(array(
    'middleware.flash' => true
));

// After instantiation
$app->config('middleware.flash', false);
Data Type
boolean
Default Value
true

middleware.prettyExceptions

Enable/disable display of formatted Exception messages.

// During instantiation
$app = \Skinny\Skinny::newInstance(array(
    'middleware.prettyExceptions' => true
));

// After instantiation
$app->config('middleware.prettyExceptions', false);
Data Type
boolean
Default Value
true

output.buffered

Enable/disable output buffering. Setting can be changed only prior to call() being invoked.

// During instantiation
$app = \Skinny\Skinny::newInstance(array(
    'output.buffered' => true
));

// After instantiation
$app->config('output.buffered', false);
Data Type
boolean
Default Value
true

inputOpts

This configuration option was added specifically to support PUT stream file upload via AJAX. You may find other uses for it. Input options must be set during instantiation. It is either false or an associative array with the following keys:

  • limit — (required) maximum bytes allowed for PUT stream upload. (Not limited by upload_max_filesize in php.ini.)
  • auth — (required) can be anything the app needs, but is evaluated by the framework with a cast to boolean.
  • abortfile — (optional) unique file name monitored to signal an input error, including user abort of a stream upload. If this file is created to signal user abort it must be an empty file. The framework will write any input error code to this file, but only if the file does not exist or has no content.
// During instantiation
$app = \Skinny\Skinny::newInstance(array(
    'inputOpts' => false
));
Data Type
mixed: false | assoc_array
Default Value
false

Names and Scopes

When you build a Skinny application you will enter various scopes in your code (e.g. global scope and function scope). You will likely need a reference to your Skinny application in each scope. There are several ways to do this:

  • Use application names with the Skinny application’s getInstance() static method
  • Curry an application instance into function scope with the use keyword

Application Names

Heads Up! Every Skinny application instance must have a unique name. Using the name of an existing instance with newInstance() will reset that instance to its newly intialized state. Use getInstance($name) to retrieve a reference to and existing app instance without resetting it.

Every Skinny application instance is given a name, whether or not you provide one. If you don't provide a name as the second argument of newInstance() the name, 'default', will be applied. Names allow you get a reference to a Skinny application instance in any scope throughout your code. Here is how you set and get an application’s name:

<?php
// name is assigned when you create a new instance. If not provided 'default' is used.
$settings = ['debug' => true];
$app = \Skinny\Skinny::newInstance($settings, 'foo');
$name = $app->getName(); // "foo"

Scope Resolution

So how do you get a reference to your Skinny application? The example below demonstrates how to obtain a reference to a Skinny application within a route callback function. The $app variable is used in the global scope to define the HTTP GET route. But the $app variable is also needed within the route’s callback scope to render a template.

<?php
$app = \Skinny\Skinny::newInstance();
$app->get('/foo', function () {
    $app->render('foo.php'); // <-- ERROR
});

This example fails because the $app variable is unavailable inside the route callback function.

Currying

We can inject the $app variable into the callback function with the use keyword:

<?php
$app = \Skinny\Skinny::newInstance();
$app->get('/foo', function () use ($app) {
    $app->render('foo.php'); // <-- SUCCESS
});

Fetch by Name

You can use the Skinny application’s getInstance() static method, too:

<?php
$app = \Skinny\Skinny::newInstance();
$app->get('/foo', 'foo');
function foo() {
    $app = Skinny::getInstance();
    $app->render('foo.php');
}

Modes

It is common practice to run web applications in a specific mode depending on the current state of the project. If you are developing the application, you will run the application in “development” mode; if you are testing the application, you will run the application in “test” mode; if you launch the application, you will run the application in “production” mode.

Skinny supports the concept of modes in that you may define your own modes and prompt Skinny to prepare itself appropriately for the current mode. For example, you may want to enable debugging in “development” mode but not in “production” mode. The examples below demonstrate how to configure Skinny differently for a given mode.

What is a mode?

Technically, an application mode is merely a string of text — like “development” or “production” — that has an associated callback function used to prepare the Skinny application appropriately. The application mode may be anything you like: “testing”, “production”, “development”, or even “foo”.

How do I set the application mode?

Heads Up! The application mode may only be set during application instantiation. It may not be changed afterward.

Use an environment variable

If Skinny sees an environment variable named “SKINNY_MODE”, it will set the application mode to that variable’s value.

<?php
$_ENV['SKINNY_MODE'] = 'production';

Use application setting

If an environment variable is not found, Skinny will next look for the mode in the application settings.

<?php
$app = \Skinny\Skinny::newInstance(array(
    'mode' => 'production'
));

Default mode

If the environment variable and application setting are not found, Skinny will set the application mode to “development”.

Configure for a Specific Mode

After you instantiate a Skinny application, you may configure the Skinny application for a specific mode with the Skinny application’s configureMode() method. This method accepts two arguments: the name of the target mode and a callable function to be immediately invoked if the first argument matches the current application mode.

Assume the current application mode is “production”. Only the callable associated with the “production” mode will be invoked. The callable associated with the “development” mode will be ignored until the application mode is changed to “development”.

<?php
// Set the current mode
$app = \Skinny\Skinny::newInstance(array(
    'mode' => 'production'
));

// Only invoked if mode is "production"
$app->configureMode('production', function () use ($app) {
    $app->config(array(
        'log.enable' => true,
        'debug' => false
    ));
});

// Only invoked if mode is "development"
$app->configureMode('development', function () use ($app) {
    $app->config(array(
        'log.enable' => false,
        'debug' => true
    ));
});