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.jsonSee the new ADR in adr-001b-configuration-management.md
+Configuration 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.Configuration 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 +and the Config Ignore Auto module +to manage configuration.
+The base 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.
+Here, we can add some of the settings files that we already know needs to be +ignored and admin-respected. +But in reality, we don't need to do this manually, because of the second module:
+Config Ignore Auto is only enabled on non-development sites.
+It works by treating any settings that are updated (site settings, module
+settings etc.) as to be ignored.
+These settings will NOT be overriden on next deploy by drush config-import.
The consequences of using this setup is
+1) We need to ignore core.extension.yml, for administrators to manage modules
+ This means that we need to enable/disable new modules using code.
+ See dpl_base.install for how to do this, through Drupal update hooks.
+2) If a faulty permission has been added, or if a decision has been made to
+ remove an existing permission, there might be config that we dont want to
+ ignore, that is ignored on some libraries.
This means we'll first have to detect which libraries have overriden config
+
+```bash
+ drush config:get config_ignore_auto.settings ignored_config_entities
+ --format json
+```
+
+and then either decide to override it, or migrate the existing.
+3) A last, and final consequence, is that we need to treat permissions more + strictly that we do now.
+An example is `adminster site settings` also both allows stuff we want to
+ignore (site name), but also things we don't want to ignore (404 node ID).
+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 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:
+The tagging system we have (tags & categories) considers content as 'islands': +Two peices of content may be tagged with the same, but they do not know about +each other.
+DDF however needs a way to structure content hierarchies. +After a lot of discussion, we reached the conclusion that this can be +materialized through the breadcrumb - the breadcrumb is basically the frontend +version of the content structure tree that editors will create and manage.
+Because of this, the breadcrumb is "static" and not "dynamic" - e.g., on some +sites, the breadcrumb is built dynamically, based on the route that the user +takes through the site, but in this case, the whole structure is built by +the editors.
+However, some content is considered "flat islands" - e.g. articles and events +should not know anything about each other, but still be categorized.
+Either way, the breadcrumb also defines the URL alias.
+There are two types of breadcrumbs:
+All of this is managed by dpl_breadcrumb module.
We tried using menus instead of taxonomy, based on experience from another +project, but it caused too much confusion and a general poor admin experience. +More info about +that in the ticket comments:
+A functional breadcrumb, that is very hard to replace/migrate if we choose a +different direction.
+ + + + + + + + + + + + + +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:
+Events make up an important part of the overall activities the Danish Public +Libraries. They aim to promote information, education and cultural activity. +Events held at the library have many different formats like book readings, +theater for children, tutoring and exhibitions of art. Some of these events +are singular and some are recurring.
+We define a recurring event as an event that occurs more than once over the +course of a period of time where the primary different between each occurrence +of the event is the event start and end time.
+A simple solution to this would be to use a multi-value date range field but +there are a number of factors that makes this more challenging:
+We have decided to base our solution on the Recurring Events Drupal module.
+The purpose of the module overlaps with our need in regards to handling +recurring events. The module is based on a construct where a recurring event +consists of an event series entity which has one or more related event +instances. Each instance corresponds to an specific date when the event +occurs.
+The module solves our requirements the following way:
+The module supports creating shedules for events with daily, weekly, monthly, +and annual repetitions. Each frequency can be customized, for example, which +days of the week the weekly event should repeat on (e.g., every Tuesday and +Thursday), which days of the month events should repeat on (e.g., the first +Wednesday, the third Friday).
+Event series and instances are fieldable entities. The module relies on the +Field Inheritance Drupal module +which allows data to be set on event series and reuse it on individual +entities.
+Recurring events support exceptions in two ways:
+The Field Inheritance module supports different modes of reuse. By using the +fallback method we can allow editors override values from event series on +individual instances.
+Recurring events creates a relationship between an event series and individual +instances. Through this relationsship we can determine what other instances +might be for an individual instance.
+It is possible to create lists of individual instances of events using Views.
+Recurring events uses a lot of vertical screen real estate on form elements +needed to define schedules (recurrence type, date/time, schedule, excluded +dates).
+The module supports defining event duration (30 minutes, 1 hour, 2 hours). +This is simpler than having to potentially repeat date and time.
+Recurring events lists six maintainers on Drupal.org and is supported by +three companies. Among them is Lullabot, a well known company within the +community.
+The module has over 1.000 sites reported using the module. The latest +version, 2.0.0-rc16, was recently released on December 1th 2023.
+The dependency, Field Inheritance, currently requires two patches to +Drupal Core.
+By introducing new entity types for event series and instance has some +consequences:
+For future work related to events we have to consider when it is appropriate to +use event series and when to use event instances.
+To create a consistent data structure for events we have to use recurring +events - even for singular events.
+We may have to do work to improve the editorial experience. This should +preferably be upstreamed to the Recurring Events module.
+Going forward we will have to participate in keeping Field Inheritance patches +to Drupal Core updated to match future versions until they are merged.
+In the process two alternative Drupal modules were considered:
+The translation system described in +adr-009-translation-system +handles solely the translations added through Drupals traditional translation handling.
+But there was a wish for being able to translate configuration related strings +as well. This includes titles, labels, descriptions, +and other elements in the admin area.
+We needed to find a way to handle translation of that kind as well.
+We went for a solution where we activated the Configuration Translation +Drupal core module and added the Configuration Translation PO contrib module.
+And we added a range of custom drush commands to handle the various +configuration translation tasks.
+By sticking to the handling of PO files in configuration handling that we are +already using in our general translation handling, +we can keep the current Github workflows with some alterations.
+Unfortunately handling translations of configuration on local sites +is still as difficult as before. +Translation of configuration texts cannot be found in the standard UI strings +translation list.
+With the config translation PO files added we tried to uncover if POEditor was +able to handle two PO files simultaneously in both import and export context. +It could not.
+But we still needed, in Drupal, to be able to import two different files: +One for general translations and one for configuration translations.
+We came up with the idea that we could merge the two files going when importing +into POEditor and split it again when exporting from POEditor.
+We tried it out and it worked so that was the solution we ended up with.
+We could activate only the config_translate module and add a danish translations +in config/sync. +But then:
+We could keep the machine names of the config in English but write the titles, +labels, descriptions in Danish.
+But that would have the following bad consequences:
+Change the Potion module to be able to scan configuration translations as well.
+We did not have a clear view of the concept of localizing configuration +translations in the same manner as the Potion module scans the codebase. +It could either be cumbersome to get the two worlds to meet in the same Potion +functionalities or simply incompatible.
+ + + + + + + + + + + + + +DPL CMS exposes data and functionality through HTTP endpoints which are +documented by an OpenAPI specification as described in +a previous ADR.
+Over time this API may need to be updated as the amount of data and +functionality increases and changes. Handling changes is an important aspect +of an API as such changes may affect third parties consuming this API.
+We use URI versioning of the API exposed +by DPL CMS.
+This is a simple approach to versioning which works well with the +RESTful Web Services Drupal module +that we use to develop HTTP endpoints with. Through the specification of the +paths provided by the endpoints we can define which version of an API the +endpoint corresponds to.
+When a breaking change is made the version of the API is increased by one e.g.
+from /api/v1/events to /api/v2/events.
We consider the following changes breaking:
+The following changes are not considered breaking:
+The existing version will continue to exist.
+Header based versioning is used by +other systems exposing REST APIs +in the infrastructure of the Danish Public Libraries. However we cannot see +this approach working well with the RESTful Web Services Drupal module. +It does not deal with multiple versions of an endpoint which different +specifications.
+Versionless GraphQL APIs are a common practice +Drupal can support GraphQL through a third party module +but using this would require us to reverse our approach to API development and +specification.
+Based on this approach we can provide updated versions of our API by leveraging +our existing toolchain.
+ + + + + + + + + + + + + +In the DPL CMS, we integrate React applications within a Drupal system as +outlined in a previous ADR. Effective +JavaScript error logging is crucial for timely detection, diagnosis, and +resolution of issues. It's essential that our logging setup not only captures +client-side errors efficiently but also integrates seamlessly with Drupal's +Watchdog logging system. This allows for logs to be forwarded to Grafana for +real-time monitoring and analysis, enhancing our system's reliability and +performance monitoring capabilities.
+After evaluating several options, we decided to integrate JSNLog +via the JSNLog Drupal module for +logging JavaScript errors. This integration allows us to capture and log +client-side errors directly from our React components into our server-side +logging infrastructure.
+The module does not have a stable release at the time of writing, which + poses risks regarding reliability and ongoing support.
+During testing, it generated excessively large numbers of log entries, + which could overwhelm our logging infrastructure and complicate error analysis.
+Custom built solution:
+Significant development time and resources required to build, test, and + maintain the module.
+Lacks the community support and proven stability found in established + third-party solutions, potentially introducing risks in terms of long-term + reliability and scalability.
+Third-party services:
+Bibliotekernes Nationale Formidling (henceforth "BNF") is a national
+team handling sharing of content for libraries. The bnf_server and
+bnf_client modules support their work.
The server module is enabled on the main BNF site, which acts as a hub +for content sharing. The BNF team uses this site to create and edit +content provided for the libraries.
+The client module is enabled on library sites and handles pushing and +fetching content to/from the BNF site.
+ + + + + + + + + + + + + +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 Auto 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 -ydpl_update.install.function dpl_update_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