Keruald

Keruald is a set of libraries to build PHP applications.

Libraries

List of libraries

Package name	Description
keruald/omnitools	General purpose library
keruald/globalfunctions	Wrapper to replace our old old sites "core.php" by calls to omnitools
keruald/commands	Create simple CLI application
keruald/report	Reporting library
keruald/health	Site health check
keruald/dockerhub	Docker Hub, managing payload signatures
keruald/github	GitHub payloads for webhooks - managing payload signatures, class representations
keruald/mailgun	Mailgun API client
keruald/database	Database abstraction layer
keruald/broker	Wrapper around brokers like RabbitMQ

Developer guide

Contribution workflow

You'll find the general contribution guide at How to contribute code. Here some pointers specific for Keruald libraries.

We use a monorepo: clone the rKERUALD repository on DevCentral, you'll find your library as a direct subdirectory on it.

Each subdirectory matches:

• a resource folder, not included in packages, if starting by an underscore _ or a dot .
• a name of a package if starting by a letter, e.g. keruald/commands for commands/

New version of a library

This should be automated through Jenkins.

To publish a new version of a library:

• Create a new tag using library/version format, e.g. foo/1.2.3
• Run ./_utils/repo/export-commits-to-manyrepo.sh foo
• Tag with versions the new commits in the library repository (tags propagation isn't currently automated)
  • compare git log from monorepo and library repo
  • Add tag without any prefix in library repo, e.g. git tag 1.2.3

How to import an existing library?

First, use tomono in the PARENT DIRECTORY of the monorepo directory.

If the name of the repository is NOT "core", export it as MONOREPO_NAME environment variable.

For example, to import Keruald/GitHub library:

$ export MONOREPO_NAME=keruald
$ echo "ssh://vcs@devcentral.nasqueron.org:5022/source/github.git github" | tomono --continue
From ssh://devcentral.nasqueron.org:5022/source/github
 * [new branch]      main       -> github/main
 * [new tag]         0.1.0      -> github/0.1.0
 * [new tag]         0.1.1      -> github/0.1.1
 * [new tag]         0.2.0      -> github/0.2.0
 * [new tag]         0.2.1      -> github/0.2.1
Updated 6 paths from the index

Then follow the procedure for a new library to update the monorepo metadata.

Don't forget to use composer dump-autoload to update your local Composer autoloader.

How to create a new library?

To create a new library quux, we need a new empty manyrepo on DevCentral, a mirror on GitHub and to declare it on Packagist:

1. Declare your library in metadata.yml
2. Regenerate shared files with make regenerate (you need Python and Jinja2): that will add your repository to files like phpcs.xml
3. Create on DevCentral a new repository with a callsign starting by K for Keruald like KQUUX, and "quux" as shortname
4. Create on GitHub a new repository called keruald/quux
5. Publish on packagist

If the shortname is already taken on DevCentral, it's time to create a new task to provide a map of subdirectory/package repository.

Don't commit anything in newly created repos but contribute as usual by creating quux/ subdirectory in the monorepo

Troubleshoot

Error: Class "Keruald\GitHub\XHubSignature" not found

When a new library is imported, a new entry is added to composer.json to provide that library.

The Composer autoloader needs to be updated with composer dump-autoload.

Annex A. IDE configuration

PhpStorm

Clone the monorepo on your drive, then open it in PhpStorm to generate an .idea folder.

• Edit keruald.iml with this modules content to declare the code namespaces: https://devcentral.nasqueron.org/P300
• For code style, you can use https://github.com/nasqueron/codestyle/blob/main/JetBrains/php-codestyle.xml