Download the PHP package jelix/profiles without Composer

API to manage profiles containing access and credentials data.

A profile contains information to access to a service. A service could be a database, a web API for axampe. Inside an application, you can have different profiles for the same type of service.

JelixProfiles allows to indicate those profiles into an ini file. All credentials are then stored into a single file. When a component of your application (let's call it a "connector") needs information about a profile, it will use JelixProfiles.

installation

You can install it from Composer. In your project:

configuration

Profiles data should be stored into an ini file. This file contains connections parameters needed by your application components: SQL and NoSQL databases, SOAP web services, cache etc.

profile parameters

Each section correspond to a profile. A profile is a set of parameters of a single connection. Sections names are composed of two names, separated by a ":":

• first name is the name of the connection type, (often corresponding to the composant name)
• second name is a name of your choice. However, two names have a special meaning: default indicates the default profile to use if the profile name is not given. And __common__, described below.

The content of the section content connection parameters.

Here is an example for the JelixDatabase component (It allows to access to a SQL database):

Profile alias

You can define some profile alias, i.e. more than one name to a profile. This is useful for example when two library use a different profile name, but you want that these libraries use the same connection parameters.

Aliases are defined in a section whose name contains only the name of the connection type. An example with JelixDatabase, defining the alias "jacl2_profile" for the default profile:

An alias should not linked to an other alias.

Common parameters

It is possible to define parameters that are common to all profiles of the same type. This avoids repeating them in each profile. To do this, you must declare them in a special profile, __common__.

For example, if all connections to SQL databases must be persistent and are all on the same server:

You can of course redefine these parameters in profiles.

Using environment variables

Ini files are readed by the parse_ini_file function, and so specific syntaxes are available to indicate values coming from outside the ini file.

• You can indicate PHP constants:

In one of your ini file:

Then foo will have the value "hello world".

• You can indicate environment variables:

Example, in your ini file, you have to use this syntax ${VARIABLE_NAME}:

usage

You should use the ProfilesReader object, that will read the ini file, and store results into a ProfilesContainer object. With this object, you will be able to get data of a profile.

If you have this kind of profiles.ini file:

In the code of the component which uses JelixProfiles:

Note that you have to give a cache file to readFromFile. It allows JelixProfiles to save extra parameters computed during the loading of the ini file.

Virtual profile

You can use a profile which is not declared into the ini file. So you can use a connection whose information are known only during the execution.

A virtual profile must be created before using your component. Use createVirtualProfile() method of the object ProfilesContainer and pass the type name of connection, a name and an array of parameters.

Example:

Of course, all parameters defined in a __common__ profile apply on virtual profiles.

Using plugins to check parameters

The connector, the object that use a profile, may expect to have specific parameters. It may have to check if parameters are ok before using them. It even may have to "calculate" some other parameters, depending on values it finds into given parameters.

To avoid to do these check or calculation each time the connector is instantiated, there is a solution into JelixProfiles to process these things during the first read of the profiles file, then final parameters are stored into the cache file of profiles.

You can provide a plugin that will do these checks and calculations for a specific category of profiles. This is a class which should inherits from Jelix\Profiles\ReaderPlugin, and implements the consolidate method which receives the profile parameters as an array, and which returns the completed profile.

Example:

Next, you have to indicate this plugin to ProfilesReader, by giving the list of plugins corresponding to each category.

Another way, is to provide a callback function which will return the plugin corresponding to the given category. It is useful if your plugin have a specific constructor, or if the class is loaded in a specific way.

Using plugins to instantiate automatically connectors

We saw that you can retrieve a profile, and then you have to give it to your connector object:

ProfilesContainer has a method to instantiate automatically the connector corresponding to the profile, and it allows also to use the same connector object during all the process of an http request. And your code is less heavy:

In order to use this method, the plugin must implement the Jelix\Profiles\ProfileInstancePluginInterface. It has two methods, getInstanceForPool($name, $profile) and closeInstanceForPool($name, $instance).

The first one is to instantiate the connector object. It is called by getConnector. The second method should terminate the connector object. For example, if the connector object maintain a connection to a database, closeInstanceForPool() should call its method that close the connection.