We use the RESTful Web Services and OpenAPI REST Drupal modules +to expose endpoints from Drupal as an API to be consumed by external parties.
+Drupal\rest\Plugin\ResourceBase and annotating it with @RestResourceuri_paths, route_parameters and responses in the annotation as
+ detailed as possible to create a strong specification.drush pm-enable restuidpl_login_user_token authentication provider for all resources which will
+ be used by the frontend this will provide a library or user token by default./openapi/rest?_format=json to
+ ensure looks as intendedtask ci:openapi:validate to validate the updated OpenAPI specificationtask ci:openapi:download to download the updated OpenAPI specificationdrush pm-uninstall restuidrush config-exportopenapi.jsonConfiguration management for DPL CMS is a complex issue. The complexity stems +from different types of DPL CMS sites.
+There are two approaches to the problem:
+A solution to configuration management must live up to the following test:
+drush site-install --existing-config -ydrush config-import -y and see that the change is rolled back and the
+ configuration value is back to default. This shows that Core configuration
+ will remain managed by the configuration system.drush config-import -y to see that no configuration is imported. This
+ shows that local configuration which can be managed by Editor libraries will
+ be left unchanged.drush config-import -y to see that the module is not disabled and the
+ configuration remains unchanged. This shows that local configuration in the
+ form of new modules added by Webmaster libraries will be left unchanged.We use the Configuration Ignore module +to manage configuration.
+The module maintains a list of patterns for configuration which will be ignored +during the configuration import process. This allows us to avoid updating local +configuration.
+By adding the wildcard * at the top of this list we choose an approach where
+all configuration is considered local by default.
Core configuration which should not be ignored can then be added to subsequent
+lines with the ~ which prefix. On a site these configuration entries will be
+updated to match what is in the core configuration.
Config Ignore also has the option of ignoring specific values within settings.
+This is relevant for settings such as system.site where we consider the site
+name local configuration but 404 page paths core configuration.
The Deconfig module allows developers +to mark configuration entries as exempt from import/export. This would allow us +to exempt configuration which can be managed by the library.
+This does not handle configuration coming from new modules uploaded on webmaster +sites. Since we cannot know which configuration entities such modules will +provide and Deconfig has no concept of wildcards we cannot exempt the +configuration from these modules. Their configuration will be removed again at +deployment.
+We could use partial imports through drush config-import --partial to not
+remove configuration which is not present in the configuration filesystem.
We prefer Config Ignore as it provides a single solution to handle the entire +problem space.
+The Config Ignore Auto module +extends the Config Ignore module. Config Ignore Auto registers configuration +changes and adds them to an ignore list. This way they are not overridden on +future deployments.
+The module is based on the assumption that if an user has access to a +configuration form they should also be allowed to modify that configuration for +their site.
+This turns the approach from Config Ignore on its head. All configuration is now +considered core until it is changed on the individual site.
+We prefer Config Ignore as it only has local configuration which may vary +between sites. With Config Ignore Auto we would have local configuration and +the configuration of Config Ignore Auto.
+Config Ignore Auto also have special handling of the core.extensions
+configuration which manages the set of installed modules. Since webmaster sites
+can have additional modules installed we would need workarounds to handle these.
The Config Split module allows +developers to split configurations into multiple groups called settings.
+This would allow us to map the different types of configuration to different +settings.
+We have not been able to configure this module in a meaningful way which also +passed the provided test.
+drush config-export
+ and have the appropriate configuration not ignored.core.extension is ignored Core developers will have to explicitly
+ enable and uninstall modules through code as a part of the development
+ process.There are different types of users that are interacticting with the CMS system:
+We need to be able to handle that both type of users can be authenticated and +authorized in the scope of permissions that are tied to the user type.
+We had some discussions wether the Adgangsplatform users should be tied to a +Drupal user or not. As we saw it we had two options when a user logs in:
+We ended up with desicion no. 2 mentioned above. So we create a Drupal user upon +login if it is not existing already.
+We use the OpeOpenID Connect / OAuth client module +to manage patron authentication and authorization. And we have developed a +plugin for the module called: Adgangsplatformen which connects the external +oauth service with dpl-cms.
+Editors and administrators a.k.a normal Drupal users and does not require +additional handling.
+Instead of creating a new user for every single user logging in via +Adgangsplatformen you could consider having just one Drupal user for all the +external users. That would get rid of the UUID -> Drupal user id mapping that +has been implemented as it is now. And it would prevent creation of a lot +of users. The decision depends on if it is necessary to distinguish between the +different users on a server side level.
+ + + + + + +The DPL React components needs to be integrated and available for rendering in +Drupal. The components are depending on a library token and an access token +being set in javascript.
+We decided to download the components with composer and integrate them as Drupal +libraries.
+As described in adr-002-user-handling +we are setting an access token in the user session when a user has been through +a succesful login at Adgangsplatformen.
+We decided that the library token is fetched by a cron job on a regular basis
+and saved in a KeyValueExpirable store which automatically expires the token
+when it is outdated.
The library token and the access token are set in javascript on the endpoint:
+/dpl-react/user.js. By loading the script asynchronically when mounting the
+components i javascript we are able to complete the rendering.
The general caching strategy is defined in another document and this focused on +describing the caching strategy of DPL react and other js resources.
+We need to have a caching strategy that makes sure that:
+We have created a purger in the Drupal Varnish/Purge setup that is able to purge
+everything. The purger is being used in the deploy routine by the command:
+drush cache:rebuild-external -y
PURGE request we found out, by studing the vcl of Lagoon, that the PURGE
+ request actually is being translated into a BAN on req.url.DPL CMS integrates with a range of other business systems through APIs. These +APIs are called both clientside (from Browsers) and serverside (from +Drupal/PHP).
+Historically these systems have provided setups accessible from automated +testing environments. Two factors make this approach problematic going forward:
+To address these problems and help achieve a goal of a high degree of test +coverage the project needs a way to decouple from these external APIs during +testing.
+We use WireMock to mock API calls. Wiremock provides +the following feature relevant to the project:
+wiremock-php
+ client library to instrument WireMock from PHP code. We modernized the
+ behat-wiremock-extension
+ to instrument with Behat tests which we use for integration testing.Software for mocking API requests generally provide two approaches:
+Generally record/replay makes it easy to setup a lot of mock data quickly. +However, it can be hard to maintain these records as it is not obvious what part +of the data is important for the test and the relationship between the +individual tests and the corresponding data is hard to determine.
+Consequently, this project prefers instrumentation.
+There are many other tools which provide features similar to Wiremock. These +include:
+wiremock-php and
+ behat-wiremock-extension libraryInstrumentation of Wiremock with PHP is made obsolete with the migration from +Behat to Cypress.
+ + + + + + +DPL CMS provides HTTP end points which are consumed by the React components. We +want to document these in an established structured format.
+Documenting endpoints in a established structured format allows us to use tools +to generate client code for these end points. This makes consumption easier and +is a practice which is already used with other +services +in the React components.
+Currently these end points expose business logic tied to configuration in the +CMS. There might be a future where we also need to expose editorial content +through APIs.
+We use the RESTful Web Services Drupal module +to expose an API from DPL CMS and document the API using the OpenAPI 2.0/Swagger +2.0 specification as supported by the +OpenAPI and OpenAPI REST +Drupal modules.
+This is a technically manageable, standards compliant and performant solution +which supports our initial use cases and can be expanded to support future +needs.
+There are two other approaches to working with APIs and specifications for +Drupal:
+DPL CMS employs functional testing to ensure the functional integrity of the +project.
+This is currently implemented using Behat +which allows developers to instrument a browser navigating through different use +cases using Gherkin, a +business readable, domain specific language. Behat is used within the project +based on experience using it from the previous generation of DPL CMS.
+Several factors have caused us to reevaluate that decision:
+We choose to replace Behat with Cypress for functional testing.
+There are other prominent tools which can be used for browser based functional +testing:
+DPL CMS is only intended to integrate with one external system: +Adgangsplatformen. This integration is necessary to obtain patron and library +tokens needed for authentication with other business systems. All these +integrations should occur in the browser through React components.
+The purpose of this is to avoid having data passing through the CMS as an +intermediary. This way the CMS avoids storing or transmitting sensitive data. +It may also improve performance.
+In some situations it may be beneficiary to let the CMS access external systems +to provide a better experience for business users e.g. by displaying options +with understandable names instead of technical ids or validating data before it +reaches end users.
+We choose to allow CMS to access external systems server-side using PHP. +This must be done on behalf of the library - never the patron.
+dpl_library_token.handler service.The current translation system for UI strings in DPL CMS is based solely on code
+deployment of .po files.
However DPL CMS is expected to be deployed in about 100 instances just to cover +the Danish Public Library institutions. Making small changes to the UI texts in +the codebase would require a new deployment for each of the instances.
+Requiring code changes to update translations also makes it difficult for
+non-technical participants to manage the process themselves. They have to find a
+suitable tool to edit .po files and then pass the updated files to a
+developer.
This process could be optimized if:
+We keep using GitHub as a central source for translation files.
+We configure Drupal to consume translations from GitHub. The Drupal translation +system already supports runtime updates and consuming translations from a +remote source.
+We use POEditor to perform translations. POEditor is a
+translation management tool that supports .po files and integrates with
+GitHub. To detect new UI strings a GitHub Actions workflow scans the codebase
+for new strings and notifies POEditor. Here they can be translated by
+non-technical users. POEditor supports committing translations back to GitHub
+where they can be consumed by DPL CMS instances.
This approach has a number of benefits apart from addressing the original +issue:
+.po files.A consequence of this approach is that developers have to write code that
+supports scanning. This is partly supported by the Drupal Code Standards. To
+support contexts developers also have to include these as a part of the t()
+function call e.g.
// Good
+$this->t('A string to be translated', [], ['context' => 'The context']);
+$this->t('Another string', [], ['context' => 'The context']);
+// Bad
+$c = ['context' => 'The context']
+$this->t('A string to be translated', [], $c);
+$this->t('Another string', [], $c);
+We could consider writing a custom sniff or PHPStan rule to enforce this
+For covering the functionality of scanning the code we had two potential +projects that could solve the case:
+ +Both projects can scan the codebase and generate a .po or .pot file with the
+translation strings and context.
At first it made most sense to go for Potx since it is used by
+localize.drupal.org and it has a long history.
+But Potx is extracting strings to a .pot file without having the possibility
+of filling in the existing translations. So we ended up using Potion which can
+fill in the existing strings.
A flip side using Potion is that it is not being maintained anymore. But it +seems quite stable and a lot of work has been put into it. We could consider to +back it ourselves.
+We considered the following alternatives:
+DPL-CMS relies on two levels of caching. Standard Drupal Core caching, and +Varnish as an accelerating HTTP cache.
+The Drupal Core cache uses Redis as its storage backend. This takes the load off +of the database-server that is typically shared with other sites.
+Further more, as we rely on Varnish for all caching of anonymous traffic, the +core Internal Page Cache module has been disabled.
+Varnish uses the standard Drupal VCL from lagoon.
+The site is configured with the Varnish Purge module and configured with a +cache-tags based purger that ensures that changes made to the site, is purged +from Varnish instantly.
+The configuration follows the Lagoon best practices - reference the +Lagoon documentation on Varnish +for further details.
+ + + + + + +The following guidelines describe best practices for developing code for the DPL +CMS project. The guidelines should help achieve:
+Contributions to the core DPL CMS project will be reviewed by members of the +Core team. These guidelines should inform contributors about what to expect in +such a review. If a review comment cannot be traced back to one of these +guidelines it indicates that the guidelines should be updated to ensure +transparency.
+The project follows the Drupal Coding Standards +and best practices for all parts of the project: PHP, JavaScript and CSS. This +makes the project recognizable for developers with experience from other Drupal +projects. All developers are expected to make themselves familiar with these +standards.
+The following lists significant areas where the project either intentionally +expands or deviates from the official standards or areas which developers should +be especially aware of.
+js-.
+ Example: <div class="gallery js-gallery"> - .gallery must only be used in
+ CSS, js-gallery must only be used in JS.is-active, has-child or similar are classes that can be used as
+ an interlink between JS and CSS.gallery.scss which contains
+ .gallery, .gallery__container, .gallery__* and so on. Avoid referencing
+ other components when possible.component.scss, there must be a comment at the top, describing
+ the purpose of the component..pane-content. Use
+ the Drupal theme system to write custom HTML and use precise, descriptive
+ class names. It is better to have several class names on the same element,
+ rather than reuse the same class name for several components.$layout-width * 0.60) or give it a descriptive variable name
+ ($side-bar-width // 350px works well with the current $layout-width_).class &). The use of parent selector
+ results in complex deeply nested code which is very hard to maintain. There
+ are times where it makes sense, but for the most part it can and should be
+ avoided.dpl.dpl prefix is not required for modules which provide functionality deemed
+ relevant outside the DPL community and are intended for publication on
+ Drupal.org.Files provided by modules must be placed in the following folders and have the +extensions defined here.
+MODULENAME.*.ymlMODULENAME.moduleMODULENAME.installtemplates/*.html.twigsrc/**/*.phptests/**/*.php/css/COMPONENTNAME.css/scss/COMPONENTNAME.scssjs/*.jsimg/*.(png|jpeg|gif|svg)Programmatic elements such as settings, state values and views modules must +comply to a set of common guidelines.
+As there is no finite set of programmatic elements for a DPL CMS site these +apply to all types unless explicitly specified.
+The project follows the code structure suggested by the +drupal/recommended-project Composer template.
+Modules, themes etc. must be placed within the corresponding folder in this +repository. If a module developed in relation to this project is of general +purpose to the Drupal community it should be placed on Drupal.org and included +as an external dependency.
+A module must provide all required code and resources for it to work on its own +or through dependencies. This includes all configuration, theming, CSS, images +and JavaScript libraries.
+All default configuration required for a module to function should be +implemented using the Drupal configuration system and stored in the version +control with the rest of the project source code.
+If an existing module is expanded with updates to current functionality the +default behavior must be the same as previous versions or as close to this as +possible. This also includes new modules which replaces current modules.
+If an update does not provide a way to reuse existing content and/or +configuration then the decision on whether to include the update resides with +the business.
+Modules which alter or extend functionality provided by other modules should use +appropriate methods for overriding these e.g. by implementing alter hooks or +overriding dependencies.
+All interface text in modules must be in English. Localization of such texts +must be handled using the Drupal translation API.
+All interface texts must be provided with a context. This supports separation +between the same text used in different contexts. Unless explicitly stated +otherwise the module machine name should be used as the context.
+The project uses package managers to handle code which is developed outside of +the Core project repository. Such code must not be committed to the Core project +repository.
+The project uses two package manages for this:
+When specifying third party package versions the project follows these +guidelines:
+The project uses patches rather than forks to modify third party packages. This +makes maintenance of modified packages easier and avoids a collection of forked +repositories within the project.
+Code may return null or an empty array for empty results but must throw +exceptions for signalling errors.
+When throwing an exception the exception must include a meaningful error message +to make debugging easier. When rethrowing an exception then the original +exception must be included to expose the full stack trace.
+When handling an exception code must either log the exception and continue +execution or (re)throw the exception - not both. This avoids duplicate log +content.
+Drupal modules must use the Logging API. +When logging data the module must use its name as the logging channel and +an appropriate logging level.
+Modules integrating with third party services must implement a Drupal setting +for logging requests and responses and provide a way to enable and disable this +at runtime using the administration interface. Sensitive information (such as +passwords, CPR-numbers or the like) must be stripped or obfuscated in the logged +data.
+Code comments which describe what an implementation does should only be used +for complex implementations usually consisting of multiple loops, conditional +statements etc.
+Inline code comments should focus on why an unusual implementation has been +implemented the way it is. This may include references to such things as +business requirements, odd system behavior or browser inconsistencies.
+Commit messages in the version control system help all developers understand the +current state of the code base, how it has evolved and the context of each +change. This is especially important for a project which is expected to have a +long lifetime.
+Commit messages must follow these guidelines:
+When creating a pull request the pull request description should not contain any +information that is not already available in the commit messages.
+Developers are encouraged to read How to Write a Git Commit Message +by Chris Beams.
+The project aims to automate compliance checks as much as possible using static +code analysis tools. This should make it easier for developers to check +contributions before submitting them for review and thus make the review process +easier.
+The following tools pay a key part here:
+In general all tools must be able to run locally. This allows developers to get +quick feedback on their work.
+Tools which provide automated fixes are preferred. This reduces the burden of +keeping code compliant for developers.
+Code which is to be exempt from these standards must be marked accordingly in +the codebase - usually through inline comments (Eslint, +PHP Codesniffer). +This must also include a human readable reasoning. This ensures that deviations +do not affect future analysis and the Core project should always pass through +static analysis.
+If there are discrepancies between the automated checks and the standards +defined here then developers are encouraged to point this out so the automated +checks or these standards can be updated accordingly.
+ + + + + + +Setting up a new site for testing certain scenarios can be repetitive. To avoid +this the project provides a module: DPL Config Import. This module can be used +to import configuration changes into the site and install/uninstall modules in a +single step.
+The configuration changes are described in a YAML file with configuration entry +keys and values as well as module ids to install or uninstall.
+/admin/config/configuration/importThe yaml file has two root elements configuration and modules.
A basic file looks like this:
+configuration:
+ # Add keys for configuration entries to set.
+ # Values will be merged with existing values.
+ system.site:
+ # Configuration values can be set directly
+ slogan: 'Imported by DPL config import'
+ # Nested configuration is also supported
+ page:
+ # All values in nested configuration must have a key. This is required to
+ # support numeric configuration keys.
+ 403: '/user/login'
+
+modules:
+ # Add module ids to install or uninstall
+ install:
+ - menu_ui
+ uninstall:
+ - redis
+We use the Configuration Ignore module +to manage configuration.
+In general all configuration is ignored except for configuration which should +explicitly be managed by DPL CMS core.
+Configuration management for DPL CMS is a complex issue. The complexity stems +from the following factors:
+There are multiple types of DPL CMS sites all using the same code base:
+All these site types must support the following properties:
+This can be split into different types of configuration:
+drush site-install --existing-config -ydrush config-export -yconfig_ignore.settings.ignored_config_entities with the ~ prefixconfig_ignore.settings
+ filedrush config-export -yNB: The keys for these configuration files should already be in
+config_ignore.settings.ignored_config_entities.
drush config-export -yfunction dpl_cms_update_9000() {
+ \Drupal::service('module_installer')->install(['shortcut']);
+}
+drush updatedb -ydrush config-export -yfunction dpl_cms_update_9001() {
+ \Drupal::service('module_installer')->uninstall(['shortcut']);
+}
+drush updatedb -ydrush config-export -ydrush deployNB: It is important that the official Drupal deployment procedure is followed. +Database updates must be executed before configuration is imported. Otherwise +we risk ending up in a situation where the configuration contains references +to modules which are not enabled.
+ + + + + + + +pjK8{S=sYPq@?|3ccY|2#4x71l)N4%TmH0|
zCO{_+iJZ3Y^z_`kixJ_|7`(pn=-R7kIY~)L
zaq$3k