README

Infosophie/Tools is a collection of tools for PHP programming, i.e. basic methods that are useful and help not to reinvent the wheel every time. Infosophie/Tools consists of the modules (classes) "Debug", "Err", "Config", "Dir" and "Asset".

Infosophie\Tools are published under GPL2.0, i.e. it is open source. You may use, change and distribute it but only under the same license (GPL2.0).

Installation

There are 2 ways to install \Tools.

1. Installation with Composer

If you know composer

Infosophie/Tools is published on Packagist (https://packagist.com) for usage with Composer (https://getcomposer.org/). For installation just add the line

"infosophie/tools": "master"

at the require section in your composer.json file:

"require": {
    [... other items ...],
    "infosophie/tools": "master"
}

Composer's autoload method will include the required php files automatically.

If you do not know composer

If you do not know Composer, you definitely should get to know it. It's a very helpful tool if you plan to develop php projects! In short, Composer is a tool to manage online published php libraries (if you happen to know 'apt' from Linux: it's something simliar).

if you want to learn more about Composer, i reccomend to refer to respective ressources on the web, like e.g. https://getcomposer.org/ and to come back when you are familiar with the commands above!

If you don't want to deal with Composer, just continue reading the next chapter.

2. Manual Installation

Download

To install Infosophie\Tools manually just download the installation archive from https://go.infosophie.de/infosophie-tools

Copy Files to Webserver

Unzip the archive and copy the files to your webserver and extract it to a subfolder of your choice inside your php project. I will refer to the path to this subfolder relative to your php skript as 'path/to/infosophie/tools'.

Include Files

In order to use the methods of Infosophie/Tools, you first need to include/require the respective php files. This can be done by requiring the file include.php in the root folder of Infosophie/Tools. This file recursively will include all the required files:

require_once('path/to/infosophie/tools/include.php');

In case you do not want to use all the tools, you may also include/requrire them separately with:

require-once('/path/to/infosophie/tools/src/[Tool].php');

Where [Tool] has to be replaced whith the respective Tool's name, e.g. to use the Config-Tool, write:

require-once('/path/to/infosophie/tools/src/Config.php');

With regard to the performance of your application I reccomend to load the files only if you actually use them!

Dependent Classes

Some of the tools themselves use other tools from the library. According to the design of composer, the Tools #do not# include any files, as composer creates one single php file that includes everything needet. We have to do the same for the manual installation.

If you include/require the path/to/infosophie/tools/include.php you don't have to care for the following, as that file will include everything needed. But if you include/require the tools separately, you need to take care for the following.

The Err-Tool for example in turn uses the Debug-Tool. So if we want to use the Err-Tool, we need to require not only the Err file, but also the Debug file:

require_once('path/to/infosophie/tools/Debug.php');
require_once('path/to/infosophie/tools/Err.php');

Now the Err-Tool in turn uses a second class besides the Err class, it's the Infosophie\Tools\Err\Exception class. So we have to require this file too:

require_once('path/to/infosophie/tools/Debug.php');
require_once('path/to/infosophie/tools/Err.php');
require_once('path/to/infosophie/tools/Err/InfosophieException.php');

If you wonder what files you need to require, you may read this manual or just try to run your script in a development setting and monitor the errors that appear if a class is not existent. The namespaces reflect the folder structure and filenames. If php misses e.g. the existence of a class "Infosophie\Tools\Err\InfosophieException", you need to require the file "/path/to/infosophie/tools/Err/InfosophieException.php" as we did above.

How to use Infosophie/Tools

General Strategies

To use the tools, add the respective "use" commands at the top of your files (mind the backslashes!):

use Infosophie\Tools\Debug;
use Infosophie\Tools\Err;
use Infosophie\Tools\Dir;
use Infosophie\Tools\Config;
use Infosophie\Tools\Asset;

If you plan to not use some of the tools, leave them out for a better performance. If you installed Infosophie/Tools manually and didn't include/require one or more Tools, you consequently won't be able to "use" them!

To learn how to use the actual methods, for each tool refer to the respective chapter below!

How to use Infosophie/Tools/Asset

How to use Infosophie/Tools/Config

General Concepts

Main usage

Infosophie\Tools\Config is used to load, read and manage configuration parameters for your project. There are 3 basic methods to use:

Config::load() - this loads a configuration file from the local disk and provides its content everywhere in your project.
Config::get('key') - (after config file is loaded) returns the value for 'key' from the configuration file
Config::form() - render a page (or part of a page) containing a html formular for editing all (or a selection of) the configuration parameters.

As the configuration data is used globally in your project, we won't need to create instances (objects) from the Config class but rather use it statically, i.e. wo do not need to call something like $config = New Config(); but just call the methods statically like:

Config::load();
$value = Config::get($key);

etc...

Storage Areas

Config has three areas of configuration storage:

The default values
The values from configuration file
The runtime values

The purpose of area 2, i.e. the values from the configuration file, is obvious: it holds the settings stored in that configuration file to be retrieve by Config::get(). This is the Tool's main purpose.

But sometimes you may use parameters that cannot be store to this file as they appear only on runtime, like values that depend on user input or the current server configuration. If there is a reason to override the config file's values, you may use Config::setRuntime() to add a value with the same key. After that, Config::get() won't return the config file's value but the value set with Config::setRuntime().

In contrast, it may be that some values are not stored in the config file while your methods still need them. You need to have default values in case the config file doesn't hold any! Instead of hard coding these values in your methods, you may use Config::setDefault() to set thouse values alltogether on runtime when your script starts. Values set with Config::setDefault() will only be returned by Config::get(), if the respective setting is not defined in the config file.

In short: Config::setDefault() sets values to be used, if no value is set in the configuration file, Config::setRuntime() sets values that override the values from configuration file!

System Settings

Infosophie\Tools\Config itself set's some configuration settings on load. The represent some helpful values like e.g. an array containing the parts separated by Slash of the request URI (key '_request_uri_array'). This is needed e.g. for RESTful APIs or to make use of pretty URLs etc.

These "System Settings" always begin whith an underscore (_) to avoid confusion with the project's settings and they are stored in the Runtime area, i.e. they cannot be overwritten by settings in the configuration file.

Though it's possible to overwrite them using Config::setRuntime(), but I reccomend to not do so but rather make a copy if you feel like changing them.

The system settings are retrieved in the same way like all other settings, i.e. with Config::get(), just pass their keys starting with the underscore.

Reference

METHOD: Config::load([file])

Loads the configuration file. If you don't provide a parameter for [file], Config presumes the configuration file to be named config.php and to be located in the projects root directory (i.e. the folder of the main script file requested by the client).

The configuration file has to be a valid php file that returns an array with all the configuration values. It basic structure therefor is like

<?php
    return [
        'cfg_key_1' => 'the value',
        'cfg_key_2' => 23,
        'whatever_you_call_it' => 'etc...'
    ];

Your free to not only use strings or numbers as values but also arrays for complex data like

<?php
    return [
        'cfg_key_1' => 'the value',
        'cfg_key_2' => [
            'this_is' => 'a sub arry',
            'with_key-value-pairs' => 'itself',
        ],
        'whatever_you_call_it' => 'etc...'
    ];

It's up to you to use these values appropriately in your code. If you call the get-method on a configuration key containing an array, it returns that array:

$key_2 = Config::get('cfg_key_2');
print_r($key_2);

will have this output (supposing the example file above):

Array ( [this_is] => a sub arry [with_key-value-pairs] => itself )

METHOD: Config::get($key)

This is the main method to retrieve configuration values during runtime. Once used the class Infosophie\Tools\Debug, you may use this method anywhere in your code. It will return the respective value to the key passed as first and only parameter.

Config::get() first searches for the respective value in the runtime storage and return this value if found. If the respective key doesn't exist in the runtime storage, Config::get() searches in the configuration file. In case the key doesn't exist there either, it finally searches it in the default value storage. If the key doesn't exist anywhere, it return the boolean value FALSE. For more info see Chapter "Storage Areas".

METHOD: Config::setRuntime($key, $value)

Sets a configuration value to the runtime area

Parameters

$key: pass the key of the setting value

$value: pass the configuration value

Return

Returns void (returns nothing)

METHOD: Config::setDefault($key, $value)

METHOD: Config::htmlForm([$array])

Returns html code for a complete form for editing the configuration file.

METHOD: Config::storeForm()

Stores the changes made in the edit form (see Config::htmlForm()) to the configuration file. The form data will be retrieved directly from the global Request array ($_REQUEST). This method works only in combination with the html form provided by Config::htmlForm().

METHOD: Config::debug()

This method is not intended for production use, but only for development. It sends all current configuration settings in a human-readable json-format to STDOUT (i.e. to the browser) for debugging purposes.

METHOD: Config::init()

To automatically prepare Config for usage on load, this method is called once when the file is included/required and shouldn't be called again during runtime. To be callable, this method has to be public even if it's not intended for usage!

infosophie / tools

Maintainers

Details