Forem: Wilmer Arambula

Creating an application in Yii3 - part 4: the final

Wilmer Arambula — Mon, 09 Jan 2023 16:48:22 +0000

Part 4: The final.

The factory is useful if you need to create objects using definition syntax and/or want to configure defaults for objects created.

$container = new PSR11DependencyInjectionContainer();
$factoryConfig = [
    EngineInterface::class => [
        'class' => EngineMarkOne::class,
        '__construct()' => [
            'power' => 42,
        ],
    ]
];

$factory = new Factory($container, $factoryConfig);

$one = $factory->create(EngineInterface::class);
$two = $factory->create(
    [
        'class' => EngineInterface::class,
        '__construct()' => [
           'power' => 146,
        ],
    ],
);

In the code above we define factory config specifying that when we need EngineInterface, an instance of EngineMarkOne will be created with power constructor argument equals to 42. We also specify that all the dependencies requested by the object created should be resolved by PSR11DependencyInjectionContainer.

First call to create() uses default configuration of EngineInterface as is. Second call specifies custom configuration for power constructor argument. In this case, configuration specified is merged with default configuration overriding its keys when the key name is the same.

The factory always create new instance. The container di create new instance once and return same on next calls.

Now that we are clear about the concepts of configuration, container di and factory, let's see the complexity of creating an app.

composer create-project --prefer-dist --stability=dev yiisoft/app app-template

Take a look at the configuration, and you'll see that changing it is as simple as changing a parameter in params.php, we've developed the right tools, that will do the job for you, that's simplicity.

Welcome to Yii3.

In the next post we will talk about assets, view, widget, db and active-record.

Wilmer Arámbula.

Team Developer YiiFramework
Twitter follow

Creating an application in Yii3 - part 3 the container di.

Wilmer Arambula — Fri, 06 Jan 2023 15:55:35 +0000

In our post today, we will talk about the container di, but first we must know some important terms, which will help us understand the functioning.

Dependency injection according to Wikipedia “In software engineering, dependency injection is a design pattern in which an object or function receives other objects or functions that it depends on. A form of inversion of control, dependency injection aims to separate the concerns of constructing objects and using them, leading to loosely coupled programs.[1][2][3] The pattern ensures that an object or function which wants to use a given service should not have to know how to construct those services. Instead, the receiving 'client' (object or function) is provided with its dependencies by external code (an 'injector'), which it is not aware of.[4] Dependency injection helps by making implicit dependencies explicit and helps solve the following problems:[5]

How can a class be independent from the creation of the objects it depends on?
How can an application, and the objects it uses support different configurations?
How can the behavior of a piece of code be changed without editing it directly?

In addition, dependency injection is used for keeping code in-line with the dependency inversion principle.[6][7]

Fundamentally, dependency injection consists of passing parameters to a method.[8]”

Let’s look at the following example:

There are two ways of re-using things in OOP: inheritance and composition.

/**
 * Inheritance is simple.
 */
class Cache
{
    public function getCachedValue($key)
    {
        // ..
    }
}

class CachedWidget extends Cache
{
    public function render(): string
    {
        $output = $this->getCachedValue('cachedWidget');

        if ($output !== null) {
            return $output;
        }

        // ...        
    }
}

The issue here is that these two are becoming unnecessarily coupled or inter-dependent making them more fragile.

/**
 * Composition.
 */
interface CacheInterface
{
    public function getCachedValue($key);
}

final class Cache implements CacheInterface
{
    public function getCachedValue($key)
    {
        // ..
    }
}

final class CachedWidget
{
    private CacheInterface $cache;

    // Dependency injection.
    public function __construct(CacheInterface $cache)
    {
        $this->cache = $cache;
    }

    public function render(): string
    {
        $output = $this->cache->getCachedValue('cachedWidget');
        if ($output !== null) {
            return $output;
        }

        // ...        
    }
}

In the above we've avoided unnecessary inheritance and used interface to reduce coupling. You can replace cache implementation without changing so it is becoming more stableCachedWidget.

The here is a dependency: an object another object depends on. The process of putting an instance of dependency into an object () is called dependency injection. There are multiple ways to perform it:CacheInterface CachedWidget.

Constructor injection. Best for mandatory dependencies.
Method injection. Best for optional dependencies.
Property injection. Better to be avoided in PHP except maybe data transfer objects.

Using the container di: Usage of the container di is fairly simple: You first initialize it with an array of definitions. The array keys are usually interface names. It will then use these definitions to create an object whenever that type is requested. This happens for example when fetching a type directly from the container somewhere in the application. But objects are also created implicitly if a definition has a dependency to another definition.

Usually a single container is used for the whole application. It is often configured either in the entry script such as or a configuration file:index.php

use Yiisoft\Di\Container;
use Yiisoft\Di\ContainerConfig;

$config = ContainerConfig::create()->withDefinitions($definitions);
$container = new Container($config);

/**
 * Definitions.
 * Very important all the values, parameters must go between square brackets.
 */
return [
    EngineInterface::class => EngineMarkOne::class,
    'full_definition' => [
        'class' => EngineMarkOne::class,
        '__construct()' => [42],
        '$propertyName' => 'value',
        'setX()' => [42],
    ],
    'closure' => fn (SomeFactory $factory) => $factory->create('args'),
    'static_call_preferred' => fn () => MyFactory::create('args'),
    'static_call_supported' => [MyFactory::class, 'create'],
    'object' => new MyClass(),
];

As seen above an object can be defined in several ways:

In the simple case an interface definition maps an id to a particular class.
A full definition describes how to instantiate a class in more detail:
- class contains the name of the class to be instantiated.
- __construct() holds an array of constructor arguments.
- The rest of the config are property values (prefixed with ) and method calls, postfixed with . They are set/called in the order they appear in the array.$()
Closures are useful if instantiation is tricky and can better be described in code. When using these, arguments are auto-wired by type. could be used to get current container instance. ContainerInterface
If it is even more complicated, it is a good idea to move such code into a factory and reference it as a static call.
While it is usually not a good idea, you can also set an already instantiated object into the container.

Definitions is describing a way to create and configure a service, an object or return any other value. It must implement Yiisoft\Definitions\Contract\DefinitionInterface that has a single method resolve(ContainerInterface $container).

References are typically stored in the container or a factory and are resolved into object at the moment of obtaining a service instance or creating an object.

Array definition allows describing a service or an object declaratively:

use \Yiisoft\Definitions\ArrayDefinition;

$definition = ArrayDefinition::fromConfig(
    [
        'class' => MyServiceInterface::class,
        '__construct()' => [42], 
        '$propertyName' => 'value',
        'setName()' => ['Alex'],
    ],
);
$object = $definition->resolve($container);

class: contains the name of the class to be instantiated.

__construct(): holds an array of constructor arguments.

The rest of the config are property values (prefixed with $) and method calls, postfixed with (). They are set/called in the order they appear in the array.

Callable definition builds an object by executing a callable injecting dependencies based on types used in its signature:

use \Yiisoft\Definitions\CallableDefinition;

$definition = new CallableDefinition(
    fn (SomeFactory $factory) => $factory->create('args')
);
$object = $definition->resolve($container);

// or 

$definition = new CallableDefinition(
    fn () => MyFactory::create('args')
);
$object = $definition->resolve($container);

// or

$definition = new CallableDefinition(
    [MyFactory::class, 'create']
);
$object = $definition->resolve($container);

In the above we use a closure, a static call and a static method passed as array-callable. In each case we determine and pass dependencies based on the types of arguments in the callable signature.

Parameter definition resolves an object based on information from ReflectionParameter
instance:

use \Yiisoft\Definitions\ParameterDefinition;

$definition = new ParameterDefinition($reflectionParameter);
$object = $definition->resolve($container);

Value definition resolves value passed as is:

use \Yiisoft\Definitions\ValueDefinition;

$definition = new ValueDefinition(42, 'int');
$value = $definition->resolve($container); // 42

References point to other definitions so when defining a definition you can use other definitions as its dependencies:

[
    InterfaceA::class => ConcreteA::class,
    'alternativeForA' => ConcreteB::class,

    MyService::class => [
        '__construct()' => [
            Reference::to('alternativeForA'),
        ],
    ],
]

Optional reference returns null when there's no corresponding definition in container:

[
    MyService::class => [
        '__construct()' => [
            // If container doesn't have definition for `EventDispatcherInterface`
            // reference returns `null` when resolving dependencies
            Reference::optional(EventDispatcherInterface::class), 
        ],
    ],
]

Dynamic reference defines a dependency to a service not defined in the container:

[
   MyService::class => [
       '__construct()' => [
           DynamicReference::to(
                         [
                  'class' => SomeClass::class,
                  '$someProp' => 15
               ],
           )
       ]
   ]
]

In order to pass an array of IDs as references to a property or an argument, Yiisoft\Definitions\ReferencesArray or Yiisoft\Definitions\DynamicReferencesArray
could be used:

File: params.php
return [
   'yiisoft/data-response' => [
       'contentFormatters' => [
           'text/html' => HtmlDataResponseFormatter::class,
           'application/xml' => XmlDataResponseFormatter::class,
           'application/json' => JsonDataResponseFormatter::class,
       ],
   ],
];

File: contentnegotiator.php

ContentNegotiator::class => [
    '__construct()' => [
        'contentFormatters' => ReferencesArray::from(
             $params['yiisoft/data-response']['contentFormatters']
        ),
    ],
],

After explaining the functioning, it seems that the configurations are complex, but they are not, the container di, does all the work for you, applying the best practices, you just have to learn the syntax of the container and the references, and everything will be simple, now let's see the actual example in our app template.

File: config/common/logger.php

<?php

declare(strict_types=1);

use Psr\Log\LoggerInterface;
use Yiisoft\Definitions\ReferencesArray;
use Yiisoft\Log\Logger;
use Yiisoft\Log\Target\File\FileTarget;

/** @var array $params */

return [
    LoggerInterface::class => [
        'class' => Logger::class,
        '__construct()' => [
            'targets' => ReferencesArray::from(
                            [
                   FileTarget::class,
                ],
            ),
        ],
    ],
];

File: config/common/translator.php

<?php

declare(strict_types=1);

use Yiisoft\Aliases\Aliases;
use Yiisoft\Translator\CategorySource;
use Yiisoft\Translator\IntlMessageFormatter;
use Yiisoft\Translator\Message\Php\MessageSource;

/** @var array $params */

return [
    // Configure application CategorySource
    'translation.app' => [
        'definition' => static function (Aliases $aliases) use ($params) {
            return new CategorySource(
                $params['yiisoft/translator']['defaultCategory'],
                new MessageSource($aliases->get('@messages')),
                new IntlMessageFormatter(),
            );
        },
        'tags' => ['translation.categorySource'],
    ],
];

file: config/web/application.php

<?php

declare(strict_types=1);

use App\Handler\NotFoundHandler;
use Yiisoft\Definitions\DynamicReference;
use Yiisoft\Definitions\Reference;
use Yiisoft\Injector\Injector;
use Yiisoft\Middleware\Dispatcher\MiddlewareDispatcher;

/** @var array $params */

return [
    \Yiisoft\Yii\Http\Application::class => [
        '__construct()' => [
            'dispatcher' => DynamicReference::to(static function (Injector $injector) use ($params) {
                return ($injector->make(MiddlewareDispatcher::class))->withMiddlewares($params['middlewares']);
            }),
            'fallbackHandler' => Reference::to(NotFoundHandler::class),
        ],
    ],
    \Yiisoft\Yii\Middleware\Locale::class => [
        '__construct()' => [
            'locales' => $params['locale']['locales'],
            'ignoredRequests' => $params['locale']['ignoredRequests'],
        ],
        'withEnableSaveLocale()' => [false],
    ],
];

Now we understand how to do any configuration of any YiiFramework package or external, it is not necessary to have a single long and complex configuration file, we can organize it according to the group of configurations and Yii config will do the work for you, as well as the container it applies the definitions for you, with the automatic wiring facility in controllers, which makes it easy to access any container dependency without the need to use static access to it, or depend on the container itself.

In our next post we will talk about the factory, and how to get all the power, flexibility and simplicity of YiiFramework.

Wilmer Arámbula.

Team Developer YiiFramework
Twitter follow

Creating an application in Yii3 - part 2 the concept of configuration.

Wilmer Arambula — Thu, 05 Jan 2023 19:45:50 +0000

In this second post, we will cover the configuration, certainly one of the main parts when creating an app, according to Wikipedia the configuration is defined “as a data set that determines the value of some variables of a computer program or an operating system. These options are usually loaded during the start of the program and in some cases it is necessary to restart it in order to see the changes”.

YiiFramework it has a powerful tool to make configurations easier, when configuring the container di, we present Yii Config, your solution for building configurations.

Yii config is a composer plugin provides assembling of configurations distributed with composer packages. It allows putting configuration needed to use a package right inside thus implementing a plugin system. The package becomes a plugin holding both the code and its configuration.

How it works:

The package consist of two parts: composer plugin and config loader.

After composer updates its autoload file, and that happens after dump-autoload, require, update or remove, composer plugin:

Scans installed packages for config-plugin extra option in their composer.json.
Writes a merge plan into config/.merge-plan.php. It includes configuration from each package composer.json.

In the application entry point, usually index.php, we create an instance of config loader and require a configuration we need:

use Yiisoft\Config\Config;
use Yiisoft\Config\ConfigPaths;

$config = new Config(
    new ConfigPaths(dirname(__DIR__)), // defined root path.
);

$web = $config->get('web'); // access config web group.

Now once we understand the concept, let’s look at an example of our app template configuration.

The first thing is to define our configuration in the extra section of composer.json, here we will tell Yii Config, which configuration should collect, let’s see the following example:

"extra": {
    "config-plugin-options": {
        "source-directory": "config"
    },
    "config-plugin": {
        "common": "common/**.php",
        "params": "params.php",
        "web": [
            "$common",
            "web/**.php"
        ],
        "console": [
            "$common",
            "console/*.php"
        ],
    }
}

source directory: We simply define the path where our configuration files will be, it can be any name in our example we will call it config, and the plugin will automatically look for the config folder in the root directory.

config-plugin: In this section we will define our configuration skeleton, let’s see the following example:

\ root directory.
    common\ configuration to be used in all defined groups.
        - application-parameters.php
        - i18n.php
        - logger.php
        - psr17.php
        - router.php
        - translator.php         
    web\ configuration used in the web group.
        - application.php
    console\ configuration** used in the console group.
params.php

As we can see in the example above, we have defined the configuration of our packages in files .php(it doesn't matter if they are YiiFramework packages or not), this allows us to define the configuration of each component in a very simple way to understand.

file: params.php

<?php

declare(strict_types=1);

return [
    'app' => [
        'charset' => 'UTF-8',
        'locale' => 'en',
    ],
];

file: application-parameters.php

<?php

declare(strict_types=1);

use App\ApplicationParameters;

/** @var array $params */

return [
    ApplicationParameters::class => [
        'class' => ApplicationParameters::class,
        'charset()' => [$params['app']['charset']],
        'name()' => [$params['app']['name']],
    ],
];

Now we are going to understand how the definition works inside the .php file, the first thing we do is define the class to configure in our container di, in this case ApplicationParameters::class, the other thing we observe is a comment /** @ var array $params */, here we can see the magic of Yii Config, it automatically allows you to access the parameters defined in the params group, and thus be able to use them in the configuration.

Using a language analogy, we can translate the previous configuration to php in:

$applicacionParameters = (new ApplicacionParameters())
    →charset($params['app']['charset'])
    →name($params['app']['name']);

The syntax would basically be:

class/interface => [
    'class' => implementation::class,
    // very important all the values, parameters must go between square brackets.
    'property' => [value]
    'method() => [parameters],
];

Now that we understand the concept in our next post, we will fully describe our configurations, and explain in detail the use of the container di and the factory.

Wilmer Arámbula.

Team Developer YiiFramework
Twitter follow

Creating an application in Yii3 - part 1 introduction.

Wilmer Arambula — Thu, 05 Jan 2023 18:53:22 +0000

Yii3 are a set of agnostic packages that facilitate the creation of a web application, API or console. Its strength is to use what we only need, in this way, we will only have dependencies that we will use throughout the development of our project.

We are now going to give an explanation of the packages that make up a standard application in Yii3:

Yii Application Template: Template Yii3

HTTP Message. This package is a lightweight, fast, high-performance and strict implementation of the PSR-7 HTTP Message and PSR-17 HTTP Factories.
Container interface. This repository holds all interfaces related to PSR-11 (Container Interface).
PSR Http Message. This repository holds all interfaces/classes/traits related to PSR-7.
HTTP Server Request Handlers for Middleware. This repository holds the RequestHandlerInterface related to PSR-15 (HTTP Server Request Handlers).
Symfony console component. The Console component eases the creation of beautiful and testable command line interfaces.
PHP dotenv. Loads environment variables from .env to getenv(), $_ENV and $_SERVER automagically.
Yii aliases. The package aim is to store path aliases, i.e. short name representing a long path (a file path, a URL, etc.). Path alias value may have another value as its part. For example, @vendor may store path to vendor directory while @bin may store @vendor/bin.
Yii assets. The package implements client-side asset (such as CSS and JavaScript) management for PHP. It helps resolve dependencies and get lists of files ready for generating HTML <script> and <link>tags.
Yii cache. This library is a wrapper around PSR-16 compatible caching libraries providing own features. It is used in Yii Framework but is usable separately.
Yii cache-file. This package implements file-based PSR-16 cache.
Yii config. This Composer plugin provides assembling of configurations distributed with composer packages. It allows putting configuration needed to use a package right inside thus implementing a plugin system. The package becomes a plugin holding both the code and its configuration.
Yii csrf. The package provides PSR-15 middleware for CSRF protection.
Yii data-response. The package allows responding with data that is automatically converted into PSR-7 response.
Yii definitions. The package provides syntax constructs describing a way to create and configure a service or an object. It is used by yiisoft/di and yiisoft/factory but could be used in other PSR-11 compatible packages as well.
Yii di. PSR-11 compatible dependency injection container that is able to instantiate and configure classes resolving dependencies.
Yii error-handler. The package provides advanced error handling.
Yii Factory. This package provides abstract object factory allowing to create objects by given definition with dependencies resolved by a PSR-11 container.
Yii files. The package provides useful methods to manage files and directories.
Yii html. The package provides various tools to help with dynamic server-side generation of HTML.
Yii http. Constants for HTTP protocol headers, methods and statuses. All along with short descriptions and RFC links. PSR-7, PSR-17 PhpStorm meta for HTTP protocol headers, methods and statuses.ContentDispositionHeader that has static methods to generate Content-Disposition header name and value. HeaderValueHelper that has static methods to parse the header value parameters.
Yii internationalization library. The package provides common internationalization utilities: Locale stores locale information created from BCP 47 formatted string. Can parse locale string, modify locale parts, form locale string from parts, and derive fallback locale.
Yii log. This package provides PSR-3 compatible logging library. It is used in Yii Framework but is usable separately.
Yii log-target-file. This package provides the File target for the yiisoft/log. The target: Records log messages in a file, allows you to configure log files rotation and provides the ability to compress rotated log files.
Yii router. The package provides PSR-7 compatible request routing and a PSR-15 middleware ready to be used in an application. Instead of implementing routing from ground up, the package provides an interface for configuring routes and could be used with an adapter package. Currently, the only adapter available is FastRoute.
Yii router-fastroute. The package provides FastRoute adapter for Yii Router.
Yii translator. This package allows translating messages into several languages. It can work with both Yii-based applications and standalone PHP applications.
Yii translator-message-php. The package provides message storage backend based on PHP arrays to be used with [yiisoft/translator](https://github.com/yiisoft/translator) package.
Yii view. This library provides templates rendering abstraction supporting layout-view-subview hierarchy, custom renderers with PHP-based as default and more. It is used in Yii Framework but is supposed to be usable separately.
Yii console. This Yii Framework package provides a console that could be added to an application.
Yii debug.This extension provides a debugger for Yii framework applications. When this extension is used, a debugger toolbar will appear at the bottom of every page. The extension also provides a set of standalone pages to display more detailed debug information.
Yii event. This package is a configuration wrapper for the yiisoft/event-dispatcher package. It is intended to make event listener declaration simpler than you could ever imagine. All you need is to use any PSR-11 compatible DI container.
Yii yii-http. This Yii framework package provides the application class, as well as the events and handlers needed to interact with HTTP. The package is implemented using PSR-7 interfaces.
Yii yii-middleware. The package provides middleware classes that implement PSR 15. For more information on how to use middleware in the Yii Framework, see the Yii middleware guide.
Yii runner console. The package contains a bootstrap for running Yii3 console application.
Yii yii-runner. The package contains a bootstrap for running Yii3 HTTP application.
Yii yii-view. The package is an extension of the Yii View Rendering Library. It adds WEB-specific functionality and compatibility with PSR-7 interfaces.

As we can see this composed of 36 packages, we can also see, that we can integrate third-party packages, without major problem, we just need to configure it in the container di.

In the next post, we will talk about how to create the application using yiisoft/app, in addition to explaining its configuration in detail.

Wilmer Arámbula.

Team Developer YiiFramework
Twitter follow