README

include and replace requirements through yaml configuration and a few more opinionated improvements on requirements

Installation

composer require bhofstaetter/yaml-requirements

Why?

To have an easy way to overwrite and edit requirements no matter where they come from. Globally and on per page basis.
To prevent multiple versions of the same library (e.g. jQuery) being included.
To adjust the order of requirements no matter where they come from depending on the needs of the project or the current page.
To be able to deliver external requirements locally.
To have some SEO improvements

Usage

This module works similarly to the inclusion of requirements through a controller via Requirements::js/javascript(...). Requirements must be stored and configured in the YAML configuration for the desired page controller.

css: `My\Cool\PageController.yamReq_css`
javascript: `My\Cool\PageController.yamReq_javascript`

a simple but not recommendable example, that works because of preset defaults for each requirement

My\Cool\PageController:
    yamReq_css:
        https://external-domain.tld/some-styling.css:
        file-in-public-dir.css:

All requirements should have at least one `identifier and probably one version`. This way the requirement can be easily exchanged and modified. Additionally, this prevents multiple versions of a resource being included (jquery 1.7, jquery 1.8, ...). Only the latest version for the given ident will be used.

My\Cool\PageController:
    yamReq_css:
        https://external-domain.tld/some-styling.css:
            identifier: 'some-styling'
            version: '1.0.0'
        file-in-public-dir.css:
            identifier: 'shouldnt-be-here'

Requirement from theme

My\Cool\PageController:
    yamReq_css:
        client/dist/css/styles.css:
            identifier: 'theme-styles'
            resolve: 'theme'

Requirement from module

My\Cool\PageController:
    yamReq_css:
        vendor/module-name:client/dist/css/warnings.css:
            identifier: 'module-name-warnings'
            resolve: 'module'

Available requirement configuration options

`identifier`: can be used to overwrite requirements. Multiple requirements with the same identifier will be merged together. Highest version wins. Highest order wins.
`version`: version of this file, following Semver. You could you '1.999.999' or similar to say this is probably the highest version of this requirement and overwrite all other
`include`: single | combined | block
`order`: a number to define the inclusion order of a requirement
`resolve`: none | module | theme (none is used for files directly inside the public folder and external resources)
`preload`: true | false
`download`: true | false (try to download external resources and server them locally, even combined)
`preConnect`: true | false

Configuration

Remove all other requirements

Removes all requirements that were not included via YamlRequirements module

bhofstaetter\YamlRequirements\RequirementsControllerExtension:
    yamReq_clear_all_regular: true # default is false

Set some defaults for a single requirement

bhofstaetter\YamlRequirements\Collector:
    default_download: true # try to download an external file and serve it locally
    default_preload: false # insert preload tag for the requirement instead of a regular link
    default_preConnect: true # add a preconnect link for an external resource
    default_resolve: 'none'
    default_order: 500

Block requirements on page level

My\Cool\PageController:
    yamReq_block_inherited_css: true # prevents the inclusion from all parent controllers css requirements
    yamReq_block_inherited_javascript: true  # prevents the inclusion from all parents controllers js requirements
    yamReq_block_css: true # prevents the inclusion from any css
    yamReq_block_javascript: true # prevents the inclusion from any js

Todo

Error Logging to Logfile
Order "Shortcuts" like DefaultModuleOrder (500) or DefaultThemeOrder(300) or DefaultCustomOrder(100)
transform regular requirements to yaml requirements (task to list them?)
task to download external requirements?
check when a downloaded file will be refreshed

bhofstaetter / yaml-requirements

Maintainers

Details