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

> ## Agent Instructions
> OwnPay is licensed under AGPL-3.0 and is completely free - no licensing fees.
> Production docs URL: https://ownpay.org/docs - append .md to any page URL for clean markdown.
> OwnPay requires PHP 8.3+, MySQL/MariaDB, and Redis.
> MCP server available at https://ownpay.org/docs/mcp for programmatic documentation queries.
> Use root-relative links (e.g. /quickstart) for internal navigation - do NOT include /docs prefix.
> Plugin development: consult /developer/plugin-types/ pages for correct interfaces and manifests.

# Plugin System - WordPress-Style Plugin Architecture

> WordPress-style plugin architecture for gateways, themes, and addons with lifecycle hooks, filters, capability declarations, and event callbacks.

How does OwnPay let you add new payment methods, themes, and features without touching the core? OwnPay uses a plugin system to extend functionality without modifying core code. Plugins reside in `modules/` and register callbacks via the `EventManager` hook loop.

## Plugin types

### Gateway plugins

Add new payment methods (Stripe, bKash, bank transfer, crypto). Provides payment processing, settlement management, webhook handling, and refund logic.

### Addon plugins

Add features like advanced reporting, subscription management, inventory sync, CRM integration, or email customization. Provides admin pages, API endpoints, scheduled jobs, and UI components.

### Theme plugins

Customize the checkout experience with custom templates, CSS, JavaScript, and branding. Provides Twig templates, stylesheets, and asset management.

## Plugin lifecycle

```text theme={null}
Discover -> Manifest Validate -> Footgun Scan -> PSR-4 Register -> register() -> boot()
```

1. **Discovery** - Plugin loader scans `modules/` directory
2. **Registration** - Plugin class loaded and registered
3. **Configuration** - Config files read and validated
4. **Activation** - Plugin hooks registered
5. **Runtime** - Plugin responds to events
6. **Deactivation** - Plugin hooks unregistered

## Plugin structure

```text theme={null}
modules/
+-- gateways/
|   +-- stripe/
|       +-- manifest.json
|       +-- src/
|       |   +-- StripeGateway.php
|       |   +-- Hooks.php
|       +-- resources/
|           +-- views/
```

### manifest.json

```json theme={null}
{
  "slug": "stripe",
  "name": "Stripe Payment Gateway",
  "version": "1.0.0",
  "type": "gateway",
  "entrypoint": "src/StripeGateway.php",
  "namespace": "OwnPay\\Gateways\\Stripe"
}
```

## Hooks system

**Pre-execution hooks** (modify behavior):

```php theme={null}
$amount = Hook::apply('payment.amount', $amount, $payment);
```

**Post-execution hooks** (react to events):

```php theme={null}
Hook::do('payment.completed', $payment);
```

Over 60 hooks available across OwnPay.

## Events system

```php theme={null}
Event::listen('payment.completed', function ($payment) {
    SendConfirmationEmail::dispatch($payment);
});
```

Available event categories: `payment.*`, `customer.*`, `gateway.*`, `webhook.*`, `user.*`, `system.*`.

## Trust model

Plugin upload is restricted to the platform owner. Installed plugins run with full application trust through the PSR-11 container - the same model as WordPress. The real security boundary is owner-only upload, not in-process isolation.

The footgun scanner blocks only `eval` and direct OS command execution. Ordinary PHP (reflection, callbacks, file I/O) is permitted.

## Best practices

* Follow OwnPay coding standards
* Include tests and documentation
* Validate all input and escape output
* Use parameterized queries
* Respect permissions
* Store secrets in config
* Use caching and optimize queries
* Queue heavy tasks

## Further reading

* [Plugin overview](/developer/plugins/overview) - Build and register your first plugin
* [Gateway development](/developer/plugin-types/gateway-development) - Create a custom payment gateway adapter
* [Theme development](/developer/plugin-types/theme-development) - Build custom checkout themes


## Related topics

- [WooCommerce Plugin - Accept Payments on WordPress](/docs/developer/integration/woocommerce.md)
- [OwnPay Architecture: PHP Core, Middleware, and Plugins](/docs/resources/architecture.md)
- [Developer Quickstart - Build Your First Payment Integration](/docs/developer/quickstart.md)
- [OwnPay FAQ: Installation, Payments, and Plugin Answers](/docs/advanced-topics/faq.md)
- [Glossary - Payment Terms and OwnPay Terminology Reference](/docs/resources/glossary.md)