Rewriting a 2017 Drupal Module for Drupal 11: Where the Time Actually Went
After my post on Digital Locker, a reader on LinkedIn asked a good question: when I moved the module to Drupal 11, which part took longer, the API changes or building automated tests around the signing flow?
The honest answer is neither. The API changes were mostly mechanical, and once the code was right the tests came quickly. The time went into something I had not planned for: finding out what the 2017 code had been getting wrong all along.

The API changes: a checklist
The Digital Locker 2.0.x rewrite touched 60 files. A lot of that was replacing APIs that no longer exist:
\Drupal::entityManager(),drupal_set_message(),file_save_data(),file_default_scheme(),file_directory_temp()and thepath.alias_managerservice.- Procedural hooks moved to
#[Hook]classes, and plugins to#[Action]and#[FieldWidget]attributes. - Requirements checks moved to
hook_runtime_requirements(), and static calls became autowired services. - The
token_vardependency, which never got a Drupal 9 release, was replaced by a module token,[digitallocker:issuer-id], with an update hook for existing patterns.
Each change is well documented in a change record, and Upgrade Status and Drupal Rector point you at most of them. It is tedious, but it is not hard.
Where the time actually went
Rewriting each file properly, rather than patching it until it ran, meant reading what every piece of code actually did. That turned up four problems that no deprecation tool would ever report.
1. The Pull API served signed certificates to anyone
DigiLocker fetches certificates from the issuer's site through a Pull API. The old route was open to everyone, and the controller never checked who was asking:
digitallocker_issuer.pull_api:
path: 'digitallocker/issuer/pull-api'
requirements:
_access: 'TRUE'Anyone who could guess a node ID could download a signed PDF for it, and not only for certificates: any node on the site.
The route still has to accept anonymous requests, because DigiLocker does not log in. What changed is that the request is now authenticated by what DigiLocker signs. Every Pull API request carries an orgId and a keyhash, a SHA-256 of the site's API key and the request timestamp. The controller verifies both before doing anything else:
if (!$this->requestSigner->verify($org_id, $timestamp, $keyhash)) {
throw new AccessDeniedHttpException('Invalid credentials.');
}The comparison uses hash_equals(), a site with no credentials configured refuses every request, and only content types marked as certificate types can be served at all.
The requester side had a similar gap: its callback now needs a permission and a CSRF token, and the browser can no longer choose the filename a document is saved under.
2. Signatures that were silently empty
This was the one that took longest to understand. The old code signed the PDF like this:
$pdf->setSignature($certificate, $certificate, $priv_key_pass, '', 1, $info);It looks right, it runs without errors, and it produces a PDF. But TCPDF only reads a certificate from disk when the path starts with file://. A bare path is treated as the certificate content itself, which is not a valid certificate, so the document came out with an empty signature and nothing complained.
$pdf->setSignature(
'file://' . $certificate,
'file://' . $certificate,
(string) $config->get('certificate_pass'),
$extra_certs !== NULL ? 'file://' . $extra_certs : '',
1,
$info,
);A bug like this is the worst kind for a module whose whole job is signed documents: everything looks like it works.
3. An Aadhaar number does not fit in an integer
Certificate types store the recipient's Aadhaar number, so the document can be pushed to the right DigiLocker account. Aadhaar numbers are 12 digits, too large for the integer field the module offered. It now uses a text field. An identifier made of digits is still not a number: you never do arithmetic on it.
4. A private key committed to the repository
The example submodule shipped with a certificate and private key in Git. It was meant to make the demo work out of the box. In practice, a key that every installation shares is not a secret. It is gone, and each site now supplies its own certificate, kept outside the repository.
And one more, found after the rewrite
The XML parsing in the Pull API, the requester and the Push API still accepted entity declarations. That was fixed separately in #3286990: any message containing a <!DOCTYPE is now rejected, and parsing runs with network access turned off.
Then the tests were easy
Once the code was right, writing tests around it was quick, because each bug above had already described exactly what to test. There is a unit test for the request signer, including the hash DigiLocker documents and each way verification should fail, and a kernel test for the Pull API that covers every way it should say no:
- an unsigned request, a wrong
keyhashand a wrongorgIdare denied; - a node that is not a certificate type, and an unknown URI, return not found;
- an empty body, malformed XML, an oversized body, an external entity and entity expansion are rejected;
- and a correctly signed request returns a document that starts with
%PDF.
All of this runs on every merge request in the drupal.org GitLab CI, alongside PHPCS and PHPStan.
What the tests do not cover yet
To be honest about the original question: the signature itself is not tested automatically yet. The kernel test checks that a signed request gets a PDF back, but not that the PDF carries a valid signature from the configured certificate. The file:// bug would slip straight past it. Generating a throwaway certificate in the test and checking the signature in the output is on the list, and it is a good first issue if you want to help.
A checklist for upgrading an old contrib module
- Run Upgrade Status and Rector first, and treat their output as the easy part of the job.
- Read every route's access requirements. Anything with
_access: 'TRUE'needs a reason, written down next to it. - Check that security-critical calls actually work, not just that they run. Signing, encryption and hashing can fail silently.
- Look for secrets in the repository, including in example and test modules.
- Check field types against real data. Identifiers made of digits belong in text fields.
- Parse untrusted XML defensively: no entity substitution, no network access, and reject a
DOCTYPEyou do not expect. - Write a test for each bug you fix, then set up GitLab CI so they keep running.
- Write down what the tests do not cover. That list is your next set of issues.
What is next
The roadmap post covers the plan: Sign in with DigiLocker, protecting Aadhaar numbers on certificates, and the move from TCPDF, which its author has deprecated in favour of tc-lib-pdf. That move is exactly where a signature test will earn its keep.
If you maintain an old contrib module and want a second pair of eyes on the upgrade, or your organisation needs DigiLocker integration as part of a larger Drupal project, I work at Axelerant and am happy to connect you with the team. Get in touch.

