Coding standards and quality tools

​

PHP conventions

• PSR-12 formatting and PSR-4 autoloading.
• Every file starts with declare(strict_types=1); after the opening tag.
• Type every property, parameter and return value. Use union and nullable types instead of untyped values.
• Add #[Override] when you implement or override a method, and import Override.
• Use constructor property promotion for dependencies.
• Keep classes final-ish in spirit: prefer composition and small services over deep inheritance.

<?php

declare(strict_types=1);

namespace Acme\Hello\Services;

use Override;
use Psr\Http\Client\ClientInterface;

class RateFetcher implements RateFetcherInterface
{
    public function __construct(
        private ClientInterface $client,
    ) {}

    #[Override]
    public function fetch(string $code): float
    {
        // ...
    }
}

​

Naming

​

Domain modeling

• Value objects validate their input in the constructor and throw Shared\Domain\Exceptions\InvalidValueException when it’s wrong. They’re immutable.
• Entities expose behavior, not setters for every field. They take value objects, not raw scalars.
• Commands are simple data holders that convert scalars into value objects, and they’re tagged with #[Handler(...)].
• Handlers do the work, persist through a repository, and dispatch a domain event.

<?php

declare(strict_types=1);

namespace Acme\Notes\Application\Commands;

use Acme\Notes\Application\CommandHandlers\CreateNoteCommandHandler;
use Acme\Notes\Domain\ValueObjects\Title;
use Shared\Infrastructure\CommandBus\Attributes\Handler;

#[Handler(CreateNoteCommandHandler::class)]
class CreateNoteCommand
{
    public Title $title;

    public function __construct(string $title)
    {
        $this->title = new Title($title);
    }
}

​

Twig conventions

• Use {% extends "/layouts/main.twig" %} for app and admin pages, and put your markup in the blocks that layout defines.
• Register your own namespace and reference templates as @acme-hello/....
• Guard optional variables with is defined, because debug mode enables strict variables.
• Wrap every user-facing string in a translation function: __(), p__() with a context, n__() for plurals. Themes use the theme domain, so they call d__('theme', ...) and dp__('theme', ...).

​

JavaScript conventions

• Alpine.js drives interactivity. Register components with Alpine.data('name', () => ({ ... })).
• Call the JSON API through the window.api client so authentication headers are handled for you.
• Reuse the built-in web components, such as x-form and modal-element, instead of reimplementing them.

​

Quality tools

vendor/bin/phpcs --standard=phpcs.xml.dist extra/extensions/acme/hello/src
vendor/bin/phpstan analyse --level=5 extra/extensions/acme/hello/src

​

Testing your extension

​

Documentation and versioning

• Ship a README.md with installation and configuration steps.
• Use semantic versioning in your package’s version field, and raise it with every release, because the installer passes it to Composer.
• Record which Aikeedo versions you support.
• Translate your strings and ship the catalogs. See Plugin localization and Theme localization.

​

Related

• Modules and layers
• Testing and quality
• Plugin quickstart