Application object¶
The Application object is the main object in the SlaxWeb Framework Application. Through the Application object you access all the services, register providers with it, access configuration through the configuration service etc.
The Application class implements ArrayAccess and thus the Application class can be used as an Array when dealing with services or Application parameters.
Note
The Application object extends the Pimple Dependency Injection Container. Read its documentation as well to get a full understanding on how it works.
Using the Application object¶
The Application object is automatically injected into multiple parts of the code. When a Route is executed, an instance of the Application object is injected into the Route action as an input parameter. Hook definitions also retrieve the Application object instance as parameters. If Controllers are loaded through its loaders, they too retrieve an instance of the Application object instance.
The main reason to use the Application object is to retrieve different services and properties that have been defined in it by Service Providers. You can however also define your own services and properties in it, as long as you make sure it is defined before it is used elsewhere in the application.
Writing to Application¶
Writing to the Application object is the same as writing an item to an associative array. You need a key(property/service) name, and a value. Writing the properties is exactly the same as writing into an array. In the example we are going to write a property with the name property to the Application object:
// ...
$application["property"] = "value";
// ...
The property is now written, and can be accessed at any time. It is not write protected so, it can be overwritten at a later point in the runtime.
Writing services is just as easy, but comes with more options. There are regular services, and factories. A service is instantiated only the first time it is called, all subsequent attempts to read a service from the Application object will return the previously instantiated object from the service. To write a service to the Application you need to define a Closure and write it to the Application object. The Closure retrieves an instance of the Application as the input parameter:
<?php
use Pimple\Container as Application;
// ...
$application["service"] = function (Application $application) {
return new ServiceClass;
};
// ...
As opposed to the service, the factory Closure is executed each time the factory is read from the Application object, and it returns a new object every time. To define a factory, you also have to define a Closure same as with a service, but you need to call the factory method of the Application object with it, and store the returned value into the Application object:
<?php
use Pimple\Container as Application;
// ...
$application["service"] = $application->factory(function (Application $application) {
return new FactoryClass;
});
// ...
Warning
Take extra care when defining new services, factories, and properties to not overwrite any existing items in the Application object. This may lead to unexpected behaviour which is hard to debug!
Reading from Application¶
To retrieve or read a service or property from the Application object, read from it as you would from an array. In the example we are presuming that the Application object is set to the $application variable, and we are trying to read a service with the name servcie and a property named property:
// ...
$service = $application["service"];
$property = $application["property"];
// ...
Services¶
The Framework and all its components save all the services in the Application object with the .service or .factory appendixes in the index names. As explained above, a regular Service is instantiated only once, and its defining Closure is called only once. All subsequent calls simply return the result of said Closure, and do not re-call it. Where the Factory service is instantiated every time it is called, and its defining Closure is called every time.
Nearly all SlaxWeb Framework components will provide at least some services, through which you can use them. This is not covered in this part of the documentation, but rather with each component documentation.
Service Providers¶
Service Providers are classes that are used only for defining new services and/or properties in the Application object. The Service Providers can be registered with the Framework, and they will be executed and register all the services/properties that are defined at each request.
Service Provider classes need to be defined in the app/Providers directory and in the \App\Provider namespace. Furthermore it needs to implement the \Pimple\ServiceProviderInterface interface to be a qualified Service Provider Class. As per the interface, the class needs to define a register method. The Register method retrieves Application object as an input parameter. The register method is called when the Service Provider is registered with the Application object.
Example Service Provider class:
<?php
namespace App\Provider;
use Pimple\Container as Application;
class MyServiceProvider implements \Pimple\ServiceProviderInterface
{
public function register(Application $application)
{
$application["service"] = function (Application $application) {
// ...
return new ServiceClass;
};
}
}
Registering the Service Provider¶
The Framework provides a simple way of registering your additional Service Providers with the Application object. You simply need to add the full class name including the namespace to the providerList configuration array located in the provider.php configuration file:
<?php
// ...
$configuration["providerList"] = [
// ...
\App\Provider\MyServiceProvider::class,
// ...
];
The Framework will now instantiate the MyServiceProvider class, register it with the Application object, which will call the register method, and register all the defined services and properties with the Application, and they will be ready to use everywhere in your Application where the Application object is available.