Atlantic Business Technologies, Inc.

Author: James Robertson

  • The Drupal 10 Migration Toolbox

    The Drupal 10 Migration Toolbox

    After a number of Drupal 7 (D7) to Drupal 10 (D10) migrations, we’d like to share our tips and tricks for streamlining the process. 

    Discovery Process

    Our Drupal migration process starts the same way as any other project at ABT, with our comprehensive discovery phase. We do this to make sure that the existing Drupal 7 site is continuing to meet the needs of our customer, and whether there are new features and functionality that can be added during the migration. If the customer would like to refresh the look and feel of the site at the same time, we move on to our design phase. While the design phase is going on, we also march on with the next steps in the migration.

    Module Audits

    We developed a spreadsheet template (with conditional formatting!) to determine whether the projects used in the Drupal 7 site are Drupal 10-compatible. The Upgrade Status and Upgrade Rector modules help speed this process up, but there is still a little legwork to do to determine version numbers, patches that need to be applied, and to weed out both false positives and false negatives that the modules report.

    One thing to watch for is that the upgrade modules will report that a project has a patch to make it Drupal 10-compatible. However, if that patch includes a change to the project’s composer.json file, then the project cannot be patched with the commonly used cweagans/composer-patches library. A developer would have to either remove the project from Composer and check the patched version into the site’s repository, or the developer would have to create a fork of the project and change their composer.json file to pull the project from the forked repository. Both situations are not ideal, as then the developer would have to keep track of project updates and pull in the changes manually.

    Luckily, there is a workaround in the mglaman/composer-drupal-lenient project. The composer-drupal-lenient project allows developers to add projects to an allow list that tells Composer to ignore the Drupal core version requirement in a project’s composer.json file. If a project is reported to be Drupal 10 ready, but the maintainer hasn’t created an official Drupal 10-compatible release, then a developer can still pull in the project via Composer.

    As far as the module audit spreadsheet itself is concerned, it is a list of all the enabled projects and whether they are custom, require an update, have a D10 version, have moved into core, or have been replaced by another module for D10. This spreadsheet and the outputs of the discovery and design phases feed into the next tool, the specification tool.

    Specification Tool

    As we worked on Drupal projects, we realized that writing a specification for a Drupal site was just…hard. But, after working with customers hosted with Acquia, we stumbled upon their Drupal Spec Tool and life became much easier. Now, we still write custom feature specifications for custom features, but the basic specification for bundles, fields, menus, Views, and more are handled by the Spec Tool. We copy the existing D7 site’s structure into the tool, and then from there can audit whether to migrate the data, transform it, delete it, or create new structures for new functionality. The tool becomes a living document that describes how the site is configured in a human-readable format, which helps non-technical users. After the site structure is described in the tool, we move on to writing the actual migrations!

    Migration Projects

    The Drupal 7 to 10 migration process is probably best handled in its own post, but it’s worthwhile to mention the Composer packages and Drupal contributed projects that help us streamline the migration process. Here’s a list of tools that can get you started, and what they do:

    • The cweagans/composer-patches and mglaman/composer-drupal-lenient Composer packages mentioned earlier in the article.
    • The Upgrade Status and Upgrade Rector projects mentioned earlier in the article.
    • Configuration Split: This project is helpful for applying different site configurations for different development environments. In the context of a migration, it can allow you to set different file paths and database connections per environment.
    • Media Migration: This project helps move Drupal 7 managed files (and media entities, if the Drupal 7 site used them) into Drupal 10 media entities. It also helps convert the field types and embedded media in content.
    • Migrate Plus: The biggest advantage of this project is that migrations can be implemented as configuration entities that can be checked into your source code repository. It also adds migration API extensions and plugins that help with complicated migrations.
    • Migrate Tools: This project adds Drush support for Drupal migrations.
    • Migrate Conditions: This project adds logic condition process plugins to allow developers to migrate content based on certain conditions. For example, we used the project to migrate a content type to different content types based on a taxonomy term on the content.
    • Drush: Drush is a command line tool for Drupal, and provides many other command line functions, besides running migrations, for managing your site on the server. 

    Check in later for a deep dive of the migration process with tips, tricks, and pitfalls to avoid!

  • Upgrading Drupal 7 to Drupal 10 can be a game changer for your business. Here’s why.

    Upgrading Drupal 7 to Drupal 10 can be a game changer for your business. Here’s why.

    As with all major website changes, the upgrade from Drupal 7 to Drupal 10 may be intimidating to plan. Despite the time investment, fully recognizing the benefits of the newest version of Drupal will be well worth your while. Read on to learn more about how upgrading will help your business through increasing efficiency, security, and an improved overall experience for your team.

    Primary Benefits of Upgrading to Drupal 10

    So why should you upgrade to Drupal 10, rather than staying with Drupal 7 or moving to another platform like WordPress?

    Ensure your application is secure.

    Drupal 7 is scheduled to reach its end of life in January of 2025. This means it won’t receive security updates or bug fixes after that point. The Drupal Association has discontinued their 3rd party maintenance program for Drupal 7, so this will be your last chance to upgrade!

    The Drupal community already did the work for simple migration paths.

    The Migrate module has been moved into Drupal 10 core code, and the community has included migration scripts to migrate most Drupal 6 and Drupal 7 configuration and content to Drupal 10. If you were moving to another platform, you would have to develop your new data structures, themes, and migration scripts yourself. With Drupal 10 you can leverage the efforts of the community to migrate your data structures and content with less effort.

    Upgrading to Drupal 10 will facilitate your upgrade to Drupal 11.

    While the Drupal 7 to Drupal 10 transition requires a migration of configuration and content (because of the extensive re-factoring of Drupal’s core code), the Drupal 10 to Drupal 11 upgrade will not require a migration. The Drupal community is returning to an upgrade-in-place strategy, much like between previous versions.

    Drupal 11 will be built off of Drupal 10, with its third-party dependencies updated and some old code removed. This will result in a smoother transition between Drupal 10 and 11.

    You may be wondering: why not upgrade to Drupal 8 or 9 first? The biggest reason is that Drupal 8’s end of life was November 2021, and Drupal 9’s end-of-life was November 1, 2023!

    What Drupal 7 Problems Will Drupal 10 Solve For Me?

    There are many new features in Drupal 10 that will improve both the developer and end-user experience for your application. It’s important to recognize that even if you’re not a developer, the new developer features make it easier to develop and deploy Drupal, which leads to a more efficient process all around.

    Three Problems for Admin Users in Drupal 7

    1. Issues with Content Editing

    One of the most frequent complaints about Drupal 7 is that the content editing experience wasn’t very good. Content editors usually had to edit their content on a form, and couldn’t really see how the content looked on the page before publishing. There was a preview function, but it didn’t always work correctly or required a lot of additional development to make it useful.

    Drupal 10 seeks to improve the content editing experience by introducing a few new features. The first is Quick Edit, which allows editors to change content inline on the page they are editing, rather than going to the edit form every time. Another is Layout Builder, which allows users to easily change the layout for a page without editing its template in code. The third is by moving the CKEditor WYSIWYG editor into Drupal’s core code, which makes it easier for editors to format text without knowing how to code.

    2. Issues With Media

    Another complaint about Drupal was its handling of media. Drupal’s solution for media management was previously cobbled together from a number of modules developed by the Drupal community. While there were some popular solutions, how to implement media management was left up to the individual site builder or developer, which led to a lot of confusion.

    Drupal 10 adds a more comprehensive media management solution in its core code that allows editors to create and re-use media content around Drupal. Drupal 10 even allows editors to embed Drupal-managed media into HTML text fields, which has been a much-requested feature for years.

    3. Issues with Moderation and Workflows

    Similarly to the media solution, the solution for content moderation and workflows were usually cobbled together from contributed modules. Drupal 10 contains the Workflows and Content Moderation modules, which provide a more tightly integrated moderation experience to Drupal’s content. Drupal 10 also introduces the concept of Workspaces, which are copies of the live site that allow developers and content editors to try out their changes in a separate environment and move the changes to the live site when they are ready. The Workspaces module is experimental for now, but should be declared stable by Drupal 11.

    Four Problems for Developers in Drupal 7

    1. Issues With Drupal’s Steep Learning Curve

    Drupal has always had a reputation of being hard to learn as a developer because it has so much custom code and therefore a steep learning curve. Additionally a lot of the most popular functionality was provided by modules contributed by the community, which developers had to know about to use and had the potential to lose support over time due to being maintained by open source contributors. Drupal’s data structures were also implemented inconsistently, which led to developer confusion about how things were implemented.

    Drupal 10 addresses the problem of custom code by re-factoring much of the code to use 3rd-party libraries with a wider knowledge base. The biggest example is that some of the previous custom functionality has been replaced by the Symfony framework. Drupal 10 also uses Composer for dependency management, rather than simply downloading core code and contributed modules from drupal.org.

    Drupal 10 also moves some of the more popular and important contributed modules into core, which has a more stable contributor base and therefore lessens the risk of these important modules becoming abandoned. The most notable examples are the Views, Migrate, Internationalization, CKEditor, and Bean modules.

    The inconsistency of the data in Drupal 7 has also been addressed by making more things “entities”, which are data structures which have common methods for working with them and which can be configured in predictable ways. This helps developers better understand how to work with Drupal data and cut down on specialized, Drupal-specific knowledge required to develop with Drupal.

    2. Issues With Deployments

    Prior to Drupal 8, deploying configuration among environments was a pain and required shuffling databases around or required contributed modules like the Features module. Drupal 8 introduced the configuration management system to combat these problems and it continues to be used in Drupal 10. Developers can export site configuration to files and check them into a source code repository. Then they can import them into different instances of the site to make deployments easier and more testable.

    3. Issues With Theming

    Drupal 7 (and prior versions) were designed as a web content management system before the popularity of smartphones and tablets, so it wasn’t designed with responsive web design in mind. Responsive best practices that required back-end support had to be implemented by custom code or by contributed modules.

    Drupal 8 added the Breakpoint and Responsive Image modules. The Breakpoint module allows developers to make modules and themes aware of each other’s breakpoints. Responsive images allows developers to tell Drupal to generate different image sizes for each breakpoint, and load those images selectively in the browser. Each of these modules helps developers make great-looking and usable sites in Drupal 10 as well.

    4. Issues With Web Services

    Drupal was also designed to build browser-based experiences. In the years since, building REST-based services became more popular by developers, and developing them in Drupal required a lot of custom code or by adding contributed modules.

    Drupal 10 has built-in support to output its data in formats other than HTML, which allows Drupal more flexibility. Drupal 10 allows developers to integrate with front-end frameworks like React and Vue easier than before, and allows users to follow a COPE (Create Once, Publish Everywhere) mindset.

    Start Your Drupal 10 Upgrade Today

    Drupal 10’s new features make many improvements for developers, content editors, and ultimately end-users. While the effort of a Drupal 7 upgrade seems heavy at first, the benefits can more than make up for it in developer and user experience. Now is the time to consider moving your site to Drupal 10! Visit our Drupal 10 page to learn more and get started with a free Drupal Migration Audit from our experts.

  • A Full Guide to PHPUnit in Drupal 10

    A Full Guide to PHPUnit in Drupal 10

    Like many open-source projects, Drupal comes with automated tests that help prevent breaking changes while promoting code quality. Drupal 8 changed its testing framework for unit and functional tests from its own Simpletest framework to PHPUnit. PHPUnit is a unit testing framework hosted by GitHub and built for the PHP programming language.

    The change from Simpletest to PHPUnit follows Drupal 8’s strategy of using more third-party libraries in Drupal Core. All Simpletests have been moved to PHPUnit as of Drupal 8.7.x, and the Simpletest module was removed in Drupal 9.

    PHPUnit can handle different types of tests in Drupal core: unit tests, kernel tests, and functional tests. With these three tests, you can confirm the quality and reaction of code on edge cases in different layers.

    Unit tests test functions, methods, and classes without requiring a database connection to run. On the other hand, kernel tests test the integration of module APIs and require a database connection to be configured to run. Functional tests test the entire system and require more setup than the others. Within the functional tests, there are both browser and JavaScript tests. In addition to these PHP-based tests, you may also run core JavaScript tests using the Nightwatch framework.

    PHPUnit: Unit Tests

    Your unit tests won’t be found unless they follow specific file structure, namespace, and metadata requirements. Drush can generate stub tests for a module.

    When writing custom code, be sure to use dependency injection to make mocking easier. You can find detailed information in this blog post, or see the examples module.

    Unit test mocks are created using Prophecy.

    PHPUnit: Kernel Tests

    Per the documentation of the KernelTestBase class, kernel tests are “useful for testing some types of integrations which don’t require the overhead of a fully-installed Drupal instance, but which have many dependencies on parts of Drupal which can’t or shouldn’t be mocked.” The class partially boots Drupal, and can load the services and hooks of other modules. The documentation says that the configuration, database schema, and entity schema could be installed for some modules, but it’s not clear which modules support this.

    PHPUnit Functional Tests

    Browser Tests

    PHPUnit browser functional tests are run against a fresh Drupal installation so each test requires set up like installing modules, creating users, etc. This can be done in the BrowserTestBase::setUp() method (which is run before each test method in the class) or by writing an abstract base class (that extends BrowserTestBase) to be extended by additional test classes. You could also simply run a previous test at the beginning of the test you are writing. The results of the browser tests are saved to a directory, which can be configured in the phpunit.xml file. See PHPUnit Browser test tutorial in the Drupal documentation.

    JavaScript Tests

    PHPUnit Javascript functional tests are run against a fresh Drupal installation in an actual browser window, in order to test Javascript and AJAX functionality. They extend WebDriverTestBase. Running them requires setting up Chromedriver and Chrome/Chromium. See PHPUnit Javascript test writing tutorial in the Drupal documentation.

    Behat Tests

    While not part of Drupal core, some contributed modules also include tests using the Behat framework. Behat uses the Gherkin syntax to describe features, which are then translated to functional and UI tests.

    Behat tests would be used to test site-specific functionality and uses the site’s database, rather than a clean installation of Drupal. The Behat Drupal Extension is an open-source project that provides drivers and useful step definitions for Drupal. Tests are organized into features, scenarios, and steps. Features and scenarios can be tagged to be run in groups, or to let Behat know to use a certain driver.

    While this Gist offers a helpful list of step definitions provided by the Behat Drupal Extension, users can also run the command “behat -dl” for a list of steps defined for a system.

    Each of these steps uses a different driver, which provides a different layer of integration with Drupal.

    Blackbox Driver

    The blackbox driver operates similarly to both the PHPUnit Browser and JavaScript functional tests. If the feature or scenario isn’t tagged, it will be run in a headless browser. If the test is tagged with @javascript, Behat can use Selenium to open a browser window and run the test. Selenium can then be set up to run the tests in several different browsers.

    Drush Driver

    The Drush driver uses the Drush command line tool to complete steps. In order to use the Drush driver, the feature or scenario must be tagged with @api. The Drush driver allows tests to use all the blackbox steps, plus a few more steps like logging in and creating users. The Drush driver can be run on multiple sites via Drush aliases.

    Drupal API Driver

    The Drupal API driver provides more complex steps, but can only be run on one site at a time. Behat can be configured to use this driver when features or scenarios are tagged with @api. Behat can be configured to run either the Drush driver OR the API driver at one time.

    Custom Step Definitions

    Custom step definitions would be added to the FeatureContext.php file that gets created when Behat is initialized for a project. The step text and any arguments are set up in annotations to functions in the FeatureContext class. See the Behat documentation for details.

    Next Steps

    Unit and functional tests are a great way to help improve your code quality. Drupal core supports many different kinds of tests that focus on different parts of the system, and some tests may be better for testing different things. Look for a future blog post on how to run these tests, and incorporate automated testing into your workflow.

    Atlantic BT is well-versed in Drupal architecture, development, and testing. Learn more about our development services, or contact us to chat with an expert.

  • Drupal Upgrade: 3 Critical Reasons to Migrate to Drupal 10 Today

    Drupal Upgrade: 3 Critical Reasons to Migrate to Drupal 10 Today

    Are you comfortable with your Drupal website, but intimidated by an upgrade?

    Many businesses are enjoying the benefits of the Drupal platform, but are still on versions 6 or 7. While a Drupal upgrade could appear to be an unnecessary hassle, delaying your move to Drupal 10 could be hurting your business for several reasons.

    Drupal 6 and 7 Support is Ending

    First of all, official support for Drupal 6 has ended and support for Drupal 7 is ending in January 2025. That may seem far in the future. However, when you include annual budget, approval, and procurement cycles, plus a typical migration project timeline, you should be planning your Drupal 10 migration project today.

    Waiting for Drupal 11 Could Cost You Resources

    There were some major technology changes in Drupal 8. Thus, a Drupal upgrade to 10 from older versions like Drupal 6 or 7, will require a significant effort. You can learn more about the issues of upgrading from older versions. On the other hand, the upgrade from Drupal 10 to 11 will be relatively easy due to the similarity of code architecture.

    You might be tempted to wait for the release of version 11 and skip 10. However, remember that you also need to consider the development of community modules for version 11 – if you try to skip 10 and wait for version 11, you could get caught between the end of support for 7 and full compatibility of your needs in version 11 community modules.

    In the long run, a Drupal upgrade to 10.1 now will give your team more time to focus on content and strategy when it comes time to upgrade to Drupal 11. Avoid the time crunch of a complete site overhaul.

    Recognize the Benefits of Drupal 10 Immediately

    Upgrading to Drupal 10 now will provide immediate benefits to your team. Many features that previously required customization have been included in version 10 core functionality. In addition to performance and security improvements, Drupal 10 includes a better experience for front-end users, an improved experience for admin users, and easier development. Don’t let the fear of a Drupal upgrade project hold you back from recognizing the benefits version 10.1 now.

    Get Your Drupal Upgrade Started With a Free Assessment

    Not sure where to start? Atlantic BT can help you with a free preliminary migration assessment to help you scope your Drupal upgrade project. Contact us today to learn more.

  • Frequently Asked Questions About Major Version Upgrades for Drupal Websites.

    Frequently Asked Questions About Major Version Upgrades for Drupal Websites.

    Continued upgrades are needed to keep Drupal websites secure and to receive new feature opportunities. However, many businesses hesitate to upgrade to new versions of Drupal due to the complexity of the process. There’s no simple solution, and these projects take careful scoping and planning.

    To help you fully understand the process, we’ve compiled answers to the most common questions we see about migrations to Drupal websites.

    When are Drupal 7 and 9 end of life?

    Drupal 7 end of life has been extended several times over the years, but its final end of life date has been set for January 5, 2025 (14 years after Drupal 7 was first released). Drupal 8’s end of life was in November 2021. Drupal 9 is scheduled to hit end of life Nov 1, 2023 (the same day as the end of life for Symfony 4, which Drupal uses extensively). Drupal 10 is the latest version of Drupal, and its end of life date hasn’t been announced yet.

    When did Drupal 10 Release?

    Drupal 10 was released in December of 2022. Drupal 10.0.0 was essentially the same code as Drupal 9.5.0, with upgraded third-party libraries and deprecated legacy code. Drupal 10.1 is the current version.

    What is the migration process from 7 to 10 for Drupal websites?

    Drupal 10 has been re-architected to use more third-party PHP libraries like Symfony, so Drupal websites that are still running on Drupal 7 are required to migrate their configuration and content to upgrade to Drupal 10.

    The Drupal 10 Migration API makes this piece easy for core modules, which have pre-configured migration plugins. On the other hand, migration support for contributed modules is spotty.

    You’ll need to evaluate which modules will be difficult to migrate, and a Drupal migration audit can help determine the best course of action by answering these questions:

    • Does the module have migration support?
    • Would it be beneficial to replace it with another module before migration?
    • Could writing a custom module streamline the site’s migration?

    Is there an upgrade path from Drupal 7 to Drupal 10?

    Yes – the migration path from 7 to 10 is the same migration path as from 7 to 8.

    For Drupal websites still on Drupal 7, we recommend upgrading to Drupal 10 as soon as possible to avoid problems associated with end of life software.

    What is the Drupal 10 to 11 Upgrade Path?

    The strategy for major version releases starting with Drupal 9 has been to upgrade Drupal’s dependencies (e.g. Symfony) and deprecate legacy code, rather than re-architect like what happened between 7 and 8. This will make it easier to upgrade-in-place, rather than migrate between versions.

    Ready to get started with your Drupal website upgrade?

    Atlantic BT is experienced with custom Drupal website development and helping you evaluate your content and modules. As the end of Drupal 7 approaches, we are offering a free preliminary assessment to kickstart your Drupal 10 migration and upgrade. Contact us here to get started.

  • Choosing the Best Editor: Gutenberg vs. Drupal Layout Builder

    Gutenberg and Drupal Layout Builder are two editors aiming to solve the same challenges. Implementing either of these solutions can enable content editors to publish their own content, build pages quickly, and have the flexibility to adjust pages. No HTML, CSS, or developer knowledge is required.

    With both options, content editors can change the layout of the page without having to change templates in the source code. This makes for an easy and flexible tool to create great-looking pages.

    Depending on your content goals, one option may work better for your Drupal website than the other. Let’s take a look at the key features of each to choose the best editor for your website.

    Gutenberg Editor Pros and Cons

    Gutenberg is the new editor for WordPress 5.0+, but is is also available as a standalone library that easily integrates with Drupal.

    You will no longer have to edit a page as individual form fields that are then output by a template in the source code. Instead, content editors can create and visualize their layouts in one large form field that accepts HTML.

    Content editors assemble pages using blocks (not to be confused with Drupal Block entities, which we’ll discuss later), which are HTML elements like headings, columns, and image galleries.

    Gutenberg Pros:

    • Use quick, visual editing.
    • Gutenberg is integrated with Drupal’s new media library to find and re-use media assets.
    • You don’t have to know HTML or CSS.
    • You can use blocks developed by other open-source developers, or develop your own.

    Gutenberg Cons:

    • Individual instances of blocks and layouts aren’t reusable. That means, if users want more than one page to look the same, they have to manually lay out the content the same way each time.

    Drupal Layout Builder Pros and Cons

    Drupal Layout Builder is a new editing experience in Drupal 8.7.0+ that allows non-developers to change page layouts without changing templates in the theme’s source code. It uses a drag-and-drop interface to customize content on a page or across pages.

    Drupal Layout Builder makes more sense for a traditional Drupal page structure, where users enter data into separate form fields, or build pages using block entities. Block entities are reusable chunks of content that can have fields like the content types.

    Layout Builder allows content editors to mix the data entered into fields and block entities in new ways, which would have previously required coding know-how.

    Drupal Layout Builder Pros

    • You can reorder field output in a more visual way.
    • You can embed Blocks in the main content area in a new way (intermingled with field output).
    • The content is laid out once per page type, and every new page of that type can use that layout. You can also override the layout for individual pages.

    Drupal Layout Builder Cons

    • It only works in main content area of page.
    • It is hard to see what is overridden where.
    • There are no granular permissions for overriding individual pages.
    • Developers or site builders must still build page types and Blocks (as opposed to Gutenberg’s library of user-contributed blocks).

    How to Get the Most Out of Both Options

    With both Drupal Layout Builder and Gutenberg, it’s important to give content editors some guidelines about what components can be used where, and what should be avoided. It’s important to develop strong style guides, training programs, and governance documents to keep the site and message aligned with the website’s brand.

    Taking some time to implement standards and training will help you find the balance between flexibility in layouts and brand compliance.

    Need Help Choosing Between Technologies?

    The best technologies to use for your website will heavily depend on your business goals and types of content you are publishing. Whether you are looking for the right CMS, editor, or hosting solution; Atlantic BT can help you strategize for your next web project. Contact us to talk about your options or schedule a free consultation.