> ## 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.

# Plugin Development Guide

> Learn how to create custom plugins to extend Aikeedo v3.x functionality with proper directory structure and integration patterns.

Plugins are powerful tools that allow you to enhance and customize your Aikeedo platform. This guide will walk you through the process of building a plugin for v3.x, using a simple Currency Beacon integration as an example.

<Note>
  This guide is for Aikeedo v3.x. The plugin structure has been updated from v2.x. Plugins are now located in `/extra/extensions/` directory.
</Note>

## What are Aikeedo Plugins?

Aikeedo plugins are Composer packages that extend the functionality of your platform. They allow you to:

* Add new features and functionality
* Integrate with third-party services
* Extend existing capabilities
* Add custom currency rate providers, payment gateways, and more

<Info>
  Plugins give you the flexibility to tailor Aikeedo to your specific requirements without modifying the core codebase, ensuring easy updates.
</Info>

## Prerequisites

Before you begin, make sure you have:

* Basic knowledge of PHP and Composer
* A local development environment set up for Aikeedo
* Composer installed on your system

If you need help setting up your local environment, refer to our [Local Development Guide](/development/local-development-guide).

## Step-by-Step Plugin Creation

Let's create a plugin that integrates [CurrencyBeacon](https://currencybeacon.com) as an alternative currency rate provider for your Aikeedo platform.

### Step 1: Create the Plugin Directory

In Aikeedo v3.x, plugins are located in the `/extra/extensions/` directory. Create a new directory for your plugin:

```bash theme={null}
mkdir -p extra/extensions/heyaikeedo/currency-beacon
```

<Tip>
  The directory structure should follow the format: `yourorganization/plugin-name`. This naming convention helps identify and organize plugins consistently.
</Tip>

<Note>
  Unlike themes, plugins typically don't need a separate `/public/e/` directory unless they provide public-facing assets like CSS or JavaScript files.
</Note>

### Step 2: Create the composer.json File

Every Aikeedo plugin requires a `composer.json` file containing essential metadata and dependencies.

Create a `composer.json` file in your plugin directory (`/extra/extensions/heyaikeedo/currency-beacon/composer.json`) with the following content:

```json theme={null}
{
  "name": "heyaikeedo/currency-beacon",
  "type": "aikeedo-plugin",
  "version": "1.0.0",
  "require": {
    "heyaikeedo/composer": "^1.0.0"
  },
  "extra": {
    "entry-class": "Aikeedo\\CurrencyBeacon\\Plugin"
  },
  "autoload": {
    "psr-4": {
      "Aikeedo\\CurrencyBeacon\\": "src/"
    }
  }
}
```

Let's break down the important parts of this file:

* `name`: Must match the path to your plugin directory (`yourorganization/plugin-name`)
* `type`: Always set to `aikeedo-plugin` for Aikeedo plugins
* `version`: Defines the current version of your plugin
* `require`: Lists the dependencies, including the required `heyaikeedo/composer` package
* `extra.entry-class`: Specifies the main class of your plugin
* `autoload`: Sets up PSR-4 autoloading for your plugin's classes

<Note>
  The `heyaikeedo/composer` package is required for all Aikeedo plugins. It provides essential functionality for plugin integration.
</Note>

### Step 3: Create the Plugin Class

Now, let's create the main plugin class. This class will be responsible for initializing your plugin's functionality.

Create a file named `Plugin.php` in the `src` directory of your plugin:

```php theme={null}
<?php

declare(strict_types=1);

namespace Aikeedo\CurrencyBeacon;

use Override;
use Plugin\Domain\Context;
use Plugin\Domain\PluginInterface;

class Plugin implements PluginInterface
{
    #[Override]
    public function boot(Context $context): void
    {
        // Plugin initialization code goes here
        // For a complete implementation example, visit:
        // https://github.com/heyaikeedo/plugins-currency-beacon
    }
}
```

This class implements the `PluginInterface`, which requires a `boot` method. The `boot` method is called when your plugin is loaded by Aikeedo, allowing you to set up any necessary functionality.

### Step 4: Directory Structure

Your complete plugin structure should look like this:

```
extra/extensions/heyaikeedo/currency-beacon/
├── composer.json
└── src/
    └── Plugin.php
```

For more complex plugins, you might have additional directories:

```
extra/extensions/heyaikeedo/currency-beacon/
├── composer.json
├── src/
│   ├── Plugin.php
│   ├── Services/
│   │   └── CurrencyService.php
│   └── Config/
│       └── settings.php
└── README.md
```

### Step 5: Install the Plugin

With your plugin structure in place, you can now install it using Composer.

<Tabs>
  <Tab title="Via Composer (Packagist)">
    If your plugin is published on Packagist or a private repository:

    ```bash theme={null}
    composer require heyaikeedo/currency-beacon
    ```
  </Tab>

  <Tab title="Local Development">
    For local development, add the plugin path to your `composer.json`:

    ```json theme={null}
    {
      "repositories": [
        {
          "type": "path",
          "url": "./extra/extensions/heyaikeedo/currency-beacon"
        }
      ]
    }
    ```

    Then install:

    ```bash theme={null}
    composer require heyaikeedo/currency-beacon
    ```
  </Tab>
</Tabs>

### Step 6: Enable the Plugin

After installation, enable your plugin through the Aikeedo admin panel:

<Steps>
  <Step title="Navigate to Plugins">
    1. Log in to your Aikeedo admin panel
    2. Go to the **Plugins** section
  </Step>

  <Step title="Activate Plugin">
    1. Locate your new plugin (Currency Beacon) in the list
    2. Click the toggle or "Activate" button to enable it

    <Check>
      Your plugin is now active and functional!
    </Check>
  </Step>
</Steps>

## Best Practices

1. **Follow PSR Standards**: Use PSR-4 autoloading and PSR-12 coding standards
2. **Version Control**: Use Git to track changes and maintain version history
3. **Semantic Versioning**: Follow semver for version numbers (e.g., 1.0.0, 1.1.0, 2.0.0)
4. **Documentation**: Include a README.md with installation and usage instructions
5. **Dependencies**: Only include necessary dependencies to keep the plugin lightweight
6. **Testing**: Write tests for your plugin's functionality
7. **Compatibility**: Ensure your plugin works with the latest Aikeedo version
8. **Security**: Validate and sanitize all inputs, especially from external APIs

## Advanced Topics

### Plugin with Public Assets

If your plugin needs CSS, JavaScript, or images, create an assets directory:

```bash theme={null}
mkdir -p public/e/heyaikeedo/currency-beacon/css
mkdir -p public/e/heyaikeedo/currency-beacon/js
```

Reference assets from `/e/yourorganization/plugin-name/` in your templates.

### Using Dependency Injection

Leverage Aikeedo's dependency injection container in your plugin:

```php theme={null}
public function boot(Context $context): void
{
    $container = $context->getContainer();
    
    // Register your services
    $container->set(CurrencyService::class, function() {
        return new CurrencyService();
    });
}
```

### Hooks and Events

Use Aikeedo's event system to extend functionality:

```php theme={null}
public function boot(Context $context): void
{
    $dispatcher = $context->getEventDispatcher();
    
    $dispatcher->addListener(
        'currency.rate.fetch',
        [$this, 'handleCurrencyFetch']
    );
}
```

## Troubleshooting

### Plugin Not Appearing in Admin Panel

* Verify `composer.json` has `"type": "aikeedo-plugin"`
* Ensure the `name` field matches your directory path
* Check that `heyaikeedo/composer` is in requirements
* Run `composer dump-autoload` to refresh autoloader
* Verify file permissions on the plugin directory

### Plugin Class Not Found

* Check the `extra.entry-class` in `composer.json` matches your class namespace
* Verify PSR-4 autoload configuration is correct
* Ensure the `Plugin.php` file is in the correct directory
* Run `composer dump-autoload -o`

### Plugin Enabled But Not Working

* Check PHP error logs for exceptions
* Verify the `boot()` method is being called
* Ensure all dependencies are installed
* Check that required services are available in the container

## Example Implementation

For a complete, working example of an Aikeedo plugin, check out the [Currency Beacon Plugin Repository](https://github.com/heyaikeedo/plugins-currency-beacon) on GitHub.

This example demonstrates:

* Proper v3.x directory structure
* Service integration
* API communication
* Error handling
* Configuration management

## Related Guides

* [Plugins Overview](/development/plugins/overview) - Understanding plugins and themes
* [Local Development Guide](/development/local-development-guide) - Set up your dev environment
* [API Overview](/development/api/overview) - Advanced integration options
* [Currency Beacon Plugin](https://github.com/heyaikeedo/plugins-currency-beacon) - Example implementation

## Need Help?

If you need assistance with Aikeedo:

<CardGroup cols={2}>
  <Card title="Professional Support" icon="headset" href="https://aikeedo.com/support/">
    Get expert help from our team with a paid support subscription
  </Card>

  <Card title="Troubleshooting Guide" icon="wrench" href="/setup/troubleshooting">
    Check common issues and solutions
  </Card>
</CardGroup>

Happy plugin development! 🚀