search

laminas / documentation

Documentation repository for the Laminas Project components.
10 stars 7 forks source link

Update and extend the installation description for components #12

Open froschdesign opened 5 years ago

froschdesign commented 5 years ago

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:

froschdesign commented 5 years ago

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.

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 commented 4 years ago

@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 commented 4 years ago

@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 commented 4 years ago

@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 commented 4 years ago

@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 notifications@github.com 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 https://github.com/zendframework/documentation/issues/12?email_source=notifications&email_token=AAAGKV3VOQODAJXPZQLJG2TQQVGX3A5CNFSM4HPJ6PMKYY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOECK2DHA#issuecomment-546677148, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAAGKVYAWSKD6JBUKW5X3B3QQVGX3ANCNFSM4HPJ6PMA .

froschdesign commented 4 years ago

@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"
        }

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

"extra": {
    "zf": {
        "module": "Some\\Component"
    }
}
froschdesign commented 4 years ago

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'

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: