> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aikeedo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Aikeedo plugins

> How Aikeedo plugins are packaged, discovered and booted, what they can extend, and what they cannot do.

A plugin is a Composer package that Aikeedo loads at boot. It can add pages, API endpoints, settings screens, navigation items, scheduled work and integrations, and it can plug new implementations into the core's extension points, without you editing a single core file.

> [!NOTE]
>
> This page applies to Aikeedo 5.x. Class names, paths and signatures match the 5.0 source code.

## Anatomy of a plugin

```text theme={null}
extra/extensions/acme/hello/
├── composer.json          # package metadata; type: aikeedo-plugin
├── src/
│   └── Plugin.php         # entry class; implements PluginInterface
├── templates/             # Twig templates (any layout you like)
└── locale/                # translation catalogs
```

Two things make it a plugin:

1. `composer.json` declares `"type": "aikeedo-plugin"`, requires `heyaikeedo/composer`, and names an entry class in `extra.entry-class`.
2. The entry class implements `Plugin\Domain\PluginInterface`:

```php src/Plugin.php theme={null}
<?php

declare(strict_types=1);

namespace Acme\Hello;

use Override;
use Plugin\Domain\Context;
use Plugin\Domain\PluginInterface;
use Twig\Loader\FilesystemLoader;

class Plugin implements PluginInterface
{
    public function __construct(
        private FilesystemLoader $loader,
    ) {}

    #[Override]
    public function boot(Context $context): void
    {
        $this->loader->addPath(__DIR__ . '/../templates', 'acme-hello');
    }
}
```

The entry class is resolved from the dependency injection container, so **anything you type-hint in the constructor is injected**. That is how a plugin reaches the core: you ask for a registry, a collection or a mapper, and you register your own implementations inside `boot()`.

> [!NOTE]
>
> `Context` is read-only metadata about your package, built from its `composer.json`. It has no container or event dispatcher on it. Use constructor injection instead.

## How a plugin is loaded

```mermaid theme={null}
flowchart TD
    A[Application boots] --> B[Core service providers and module bootstrappers]
    B --> C[PluginModuleBootstrapper]
    C --> D[PluginFinder scans extra/extensions for composer.json]
    D --> E[Context built and validated per package]
    E --> F{Active and healthy?}
    F -- no --> G[Skipped]
    F -- yes --> H[PluginLoader resolves the entry class from the container]
    H --> I["boot(Context) registers routes, templates, services, listeners"]
    I --> J[HTTP request is handled]
```

Key points:

* Plugins boot **after** every core module, so all core registries exist by the time `boot()` runs.
* `boot()` runs on every request, including console and cron runs. Keep it cheap: register things, don't do work.
* Only plugins whose status is `active` boot. Themes are a special case: a theme is active when it's the selected theme.
* If a plugin crashes while booting, Aikeedo records the failure in `var/plugin-health.json` and skips the plugin on later requests, so one broken plugin can't take the site down. With `DEBUG` on, the error is raised instead. See [Debugging](https://docs.aikeedo.com/development/plugins/debugging.md).

## What plugins can extend

| Capability | Where to start |
| - | - |
| Admin settings pages | [Admin settings pages](https://docs.aikeedo.com/development/plugins/admin-settings-pages.md) |
| Pages and JSON endpoints for signed-in users | [App pages and APIs](https://docs.aikeedo.com/development/plugins/app-pages-and-apis.md) |
| Public pages, forms, endpoints and webhooks | [Public pages and endpoints](https://docs.aikeedo.com/development/plugins/public-endpoints-and-embeds.md) |
| Menu entries in the app and admin panel | [Navigation](https://docs.aikeedo.com/development/plugins/navigation.md) |
| Reactions to domain events, and scheduled work | [Events and cron](https://docs.aikeedo.com/development/plugins/events-and-cron.md) |
| Payment gateways | [Payment gateways](https://docs.aikeedo.com/development/plugins/guides/payments/overview.md) |
| Tax engines | [Tax engines](https://docs.aikeedo.com/development/plugins/guides/tax-engine.md) |
| Storage backends | [Storage adapters](https://docs.aikeedo.com/development/plugins/guides/storage-adapter.md) |
| Vector databases | [Vector stores](https://docs.aikeedo.com/development/plugins/guides/vector-store.md) |
| AI providers and models | [AI providers](https://docs.aikeedo.com/development/plugins/guides/ai-provider.md) |
| Chat tools | [AI tools](https://docs.aikeedo.com/development/plugins/guides/ai-tool.md) |
| Currency exchange rates | [Currency rate providers](https://docs.aikeedo.com/development/plugins/guides/currency-rate-provider.md) |
| Per-plan settings | [Plan config extensions](https://docs.aikeedo.com/development/plugins/guides/plan-config-extension.md) |
| Conversation import sources | [Import adapters](https://docs.aikeedo.com/development/plugins/guides/import-adapter.md) |
| Your own extension points, for other plugins to implement | [Custom extension points](https://docs.aikeedo.com/development/plugins/custom-extension-points.md) |

## What plugins cannot do

| Limitation | Why | What to do instead |
| - | - | - |
| Add Doctrine entities | Doctrine maps only the core `src/` directory | Store data in options, reuse core entities, or use your own external store. See [Data and persistence](https://docs.aikeedo.com/development/plugins/data-and-persistence.md) |
| Add database migrations | Migration paths are fixed in `config/migrations.php` | Create any schema you need from an install hook against your own connection, or avoid extra tables |
| Add console commands | The command map in `config/commands.php` is static | Expose the action as an admin endpoint, or run it from cron |
| Replace core templates | Themes and plugins add namespaces, they don't override core paths | Use `resources/views/overrides/`. See [Extending Aikeedo](https://docs.aikeedo.com/development/extending-aikeedo.md) |

## Where plugins live

| Path | Contents |
| - | - |
| `extra/extensions/{vendor}/{name}` | The installed package, where Composer puts it |
| `extra/artifacts/` | Uploaded plugin archives, used as a Composer artifact repository |
| `public/e/{vendor}/{name}` | Public assets copied from `extra.public`. See [Public assets](https://docs.aikeedo.com/development/plugins/public-assets.md) |
| `var/plugin-backup/` | Backups taken before a reinstall |
| `var/plugin-health.json` | Recorded boot failures |

## Next steps

> [card] [Build your first plugin](https://docs.aikeedo.com/development/plugins/quickstart.md)
>
> A working plugin with a settings page and a menu item, step by step.

> [card] [Manifest reference](https://docs.aikeedo.com/development/plugins/manifest.md)
>
> Every `composer.json` field Aikeedo reads.

> [card] [Lifecycle and hooks](https://docs.aikeedo.com/development/plugins/lifecycle-and-hooks.md)
>
> Install, activate, deactivate, uninstall and update.

> [card] [Services you can inject](https://docs.aikeedo.com/development/plugins/dependency-injection-and-services.md)
>
> The core services a plugin reaches through its constructor.

## Need Help?

If you need assistance with Aikeedo:

> [card] [Professional Support](https://aikeedo.com/support/?utm_source=docs\&utm_medium=content)
>
> Get expert help from our team with a paid support subscription

> [card] [Troubleshooting Guide](https://docs.aikeedo.com/setup/troubleshooting.md)
>
> Check common issues and solutions


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.