Migrating from the community Akismet module

The community Akismet module is no longer maintained, and its project page asks users to move to Akismet Anti-Spam. We're the Akismet team at Automattic, and we maintain it.

This page covers the 1.1.x releases. If it ever disagrees with the README.md in your release, trust the README.

Which path applies to your site

Find the community module release your site runs, then follow the path in its row.

Before you start

• Run Drupal 10.3 or later on PHP 8.1 or later. The community module 2.0.x runs fine on Drupal 10, so you can update core first and swap the module afterwards.
• Back up the database. The takeover only goes one way.
• Know what the takeover removes. It drops the community module's akismet table, so your new Spam tab starts empty. That table holds serialized submissions, including author email and IP addresses. The official module can't honor erasure requests for that data, so we drop the table on purpose. The takeover also deletes the akismet.form.* configuration and the community module's actions, and it replaces akismet.settings.
• Know what carries over. Your API key, a connection timeout between 1 and 60 seconds, and your comment, contact and registration protection settings all carry over. Everything else starts from the official module's defaults.

The community module protected one comment type or one contact form at a time. The official module has one setting per category: comments, contact forms, user registration and Webform. So if your site protected only some comment types or contact forms, the official module now checks all of them. The takeover report names the forms the community module covered, so you can see exactly what widened.

Migration steps

Do steps 1 to 5 once, on one environment, and commit the result. Then repeat step 6 on every other environment.

1. Remove the community module's code with composer remove drupal/akismet. Leave the module installed in Drupal. The takeover needs its database state.
2. Add the official module with composer require drupal/akismet_antispam -W. Deploy steps 1 and 2 together, because the site has no Akismet code between them. You can also run both as one command: composer remove drupal/akismet --no-update && composer require drupal/akismet_antispam -W.
3. Rebuild the cache with drush cr. Do this right away, before anything else runs. The cached service container still points at the community module's classes, and those classes are gone. Until you rebuild it, logged-in pages return a 500 error and every drush command ends in a fatal error. drush cr still works here because it builds a fresh container.
4. Run database updates with drush updb. Spam protection stays off until this finishes. Stay away from the comment admin pages until then, since they can return a 500 error. Maintenance mode won't shield you, because administrators can still browse. On PHP 8.1, /update.php can stop on a "Requirements problem" page about the PHP version. Its "try again" link (update.php?continue=1) carries on past it.
5. Read the takeover report, then export your configuration. drush updb prints the report, and the takeover also writes it to the site log. Then run drush cex, review the changes and commit them. This swaps the community module's configuration in your sync directory for the official module's.
6. Deploy to each other environment with drush cr && drush deploy. Each environment needs drush cr first, for the same reason as step 3. drush deploy then runs the takeover against that environment's database and imports the configuration you exported in step 5.

Composer won't install both modules together, which is why step 1 comes first.

After the migration

Check these on every site:

• Protection settings (/admin/config/content/akismet). Make sure the comment, contact and registration settings match what you want. If the report says it found no per-form configuration, the official module's defaults apply, and those protect comments, contact forms and webforms.
• Status report (/admin/reports/status). A "Pre-migration configuration detected" warning means an environment imported the community module's old configuration. Run drush updb, or import the configuration you exported after the migration.
• A test submission. Post a comment as an anonymous user named akismet-guaranteed-spam, which Akismet always marks as spam. With the default Strictness, it should show up on the Spam tab (/admin/content/comment/spam).

Check these when the takeover report mentions them:

• Comment spam handling. The community module could discard spam form by form. The official module has one site-wide Strictness setting, and by default it queues comment spam for review. To discard blatant comment spam again, set Strictness to "Silently discard blatant spam (comments only)".
• Contact form spam handling. By default, the official module blocks contact form submissions that Akismet flags as blatant spam. The community module had no such setting, so this is a new default. To deliver every message, set Contact form spam blocking to "Do not block".
• Webforms. Add the Akismet handler to each webform the report names. The official module checks a webform only once it has the handler.
• Unsupported forms. The report names each form the official module doesn't cover, such as the user profile or password reset forms. Protection on those forms ends with the migration.
• Bypass permission. The takeover removes the community module's "Bypass Akismet protection" permission from every role. The official module's Bypass Akismet permission starts out ungranted, so grant it wherever you need it.
• Test mode. The official module reads test mode from settings.php. To keep it on, add $settings['akismet_test_mode'] = TRUE;.
• Custom endpoint and outage policy. The official module always talks to rest.akismet.com and has no "block all submissions" outage policy. During an outage it accepts submissions and checks them again later.
• Field selection. The community module let you pick and map the fields it sent to Akismet on each form. The official module picks those fields itself.

Drupal 7 and earlier

The takeover needs Drupal 10.3 or later. If your site runs the community module 7.x-2.x, or the AntiSpam module on Drupal 7, upgrade to a current Drupal version first. Then install the official module fresh and enter your API key. Your Akismet account and API key stay the same.