Update and extend the installation description for components

[froschdesign]

Problem

Most of the installation descriptions in the components contain only the Composer command, and further steps such as registering are missing. Also the usage with zend-component-installer.

Suggestion

Create a new installation page that contains:

• Composer command
• Usage with zend-component-installer (when available)
  • For zend-mvc based applications
  • For zend-expressive based applications
  • For applications which use zend-config-aggregator
• Notice if the component can not be installed via the zend-component-installer
• Manual registering (when available)

[froschdesign]

Draft

This is a first draft for the new installation page. Comments and help are welcome!

---

Installation

Standard Installation

To install the library use Composer:

$ composer require zendframework/zend-inputfilter

Installation for zend-expressive and zend-mvc Application

Installation and Automated Configuration

The zend-component-installer is the recommended installation method when using in a zend-expressive-based or a zend-mvc-based application. It will automatically inject the config-provider or the module in the configuration during the installation process.

Installation Requirements

The following descriptions depends on the zend-component-installer component, so be sure to have it installed as development dependency before getting started:

$ composer require --dev zendframework/zend-component-installer

Install zend-inputfilter and Inject Configuration

To install the library use Composer:

$ composer require zendframework/zend-inputfilter

This will install an initial set of dependencies, including zend-filter.

It will also prompt to inject the component configuration.

• For a zend-expressive application, choose config/config.php.
• For a zend-mvc application, choose either modules.config.php or application.config.php.

If additional dependencies are to be installed, the option for other packages can be remembered.

Installation and Manual Configuration

If the installer is not used, the manual configuration is needed to add the component to the application.

Install zend-inputfilter

To install the library, use Composer:

$ composer require zendframework/zend-inputfilter

Configuration for a zend-expressive-based Application

Add the configuration provider of zend-inputfilter to the configuration file, e.g. config/config.php:

$aggregator = new Zend\ConfigAggregator\ConfigAggregator([
    // …
    Zend\Expressive\ConfigProvider::class,
    Zend\Expressive\Router\ConfigProvider::class,
    Zend\InputFilter\ConfigProvider::class, // <-- Add this line
    // …
]);

Configuration for a zend-mvc-based Application

Add zend-inputfilter as module to the configuration file for modules, e.g. config/modules.config.php:

return [
    'Zend\InputFilter', // <-- Add this line
    'Zend\Router',
    'Zend\Session',
    'Zend\Validator',
    'Application',
];

---

/cc @weierophinney @settermjd @Xerkus @webimpress

[michalbundyra]

@froschdesign It looks great. I was missing this part, and current home/installation page in the documentation could be confusing, as we are not saying any single word that the module must be enabled...

Today I have found that you don't need to have installed zendframework/zend-component-installer in the project, but it could be global installation in the system. Maybe it should be also noted - or link to zend-component-installer will be enough for more details?

This will install an initial set of dependencies, including zend-filter.

this is specific for package, how we are gonna do it for all packages?
I would see it as generic template - and in configuration we can specify "installation type: expressive, mvc, generic" etc...

Also adding something at the top of module list or the bottom is not that obvious. I guess it doesn't matter too much for ConfgProviders but there is a difference for modules - we have there two types - "Components" (added at the top of module list) and "Modules" (added at the bottom of the module list). It is also described in zend-component-installer documentation. So manual installation is not that trivial.

[froschdesign]

@webimpress
Thanks for your feedback. 👍

I would see it as generic template - and in configuration we can specify "installation type: expressive, mvc, generic" etc...

That's exactly what the goal should be! I will update the draft and will test it with documentation template.

[froschdesign]

@webimpress

Also adding something at the top of module list or the bottom is not that obvious.
…
So manual installation is not that trivial.

Currently we have no ZF components which can be installed as a module.

[weierophinney]

@froschdesign - Almost any non-expressive component that has a ConfigProvider also has a Module class - I know for certain that form, filter, validator, and mvc-i18n have them.

…

On Sun, Oct 27, 2019, 4:31 AM Frank Brückner ***@***.***> wrote: @webimpress <https://github.com/webimpress> Also adding something at the top of module list or the bottom is not that obvious. … So manual installation is not that trivial. Currently we have no ZF components which can be installed as a module. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#12>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAAGKVYAWSKD6JBUKW5X3B3QQVGX3ANCNFSM4HPJ6PMA> .

[froschdesign]

@weierophinney

Almost any non-expressive component that has a ConfigProvider also has a Module class

Right, but these module classes are installed as "component":

        "zf": {
            "component": "Zend\\Filter",
            "config-provider": "Zend\\Filter\\ConfigProvider"
        }

• https://github.com/zendframework/zend-form/blob/master/composer.json#L76
• https://github.com/zendframework/zend-filter/blob/master/composer.json#L60
• https://github.com/zendframework/zend-validator/blob/master/composer.json#L68
• https://github.com/zendframework/zend-mvc-i18n/blob/master/composer.json#L59
• …

There are no module classes which are installed as "module":

"extra": {
    "zf": {
        "module": "Some\\Component"
    }
}

[froschdesign]

I have tested the some options within the template.

For example (mkdocs.yml):

extra:
    installation:
      config_provider_class: 'Zend\InputFilter\ConfigProvider'
      module_class: 'Zend\InputFilter'

• No config_provider_class means: hide installation description for zend-expressive.
• No module_class means: hide installation description for zend-mvc.

In this way, the content of the installation description can be controlled. But this also means we must move the entire content of the installation to theme and template.
If we do it this way then we should add a new directory structure in the theme to separate the templates with content:

• theme
  • css
  • img
  • js
  • pages
    • 404.html
    • homepage.html
    • installation.html
  • partials
    • breadcrumbs.html
    • component-list.html
    • component-selector.html
    • …
  • main.html