Best Practices

Guidelines for creating secure, performant, and maintainable plugins.

Security

Never Use Dangerous Functions

Forbidden functions:

• eval(), exec(), shell_exec(), system()

• passthru(), popen(), proc_open()

• Dynamic require/include with user input

// BAD - Security vulnerability
eval($_GET['code']);
exec('rm -rf ' . $userInput);

// GOOD - Use safe alternatives
$sanitizedInput = escapeshellarg($userInput);
exec('safe-command ' . $sanitizedInput);

Validate All Input

use Symfony\Component\Validator\Constraints as Assert;

#[Assert\NotBlank]
#[Assert\Email]
private string $email;

#[Assert\Length(min: 8, max: 100)]
private string $password;

#[Assert\Range(min: 1, max: 100)]
private int $age;

Use Parameterized Queries

// GOOD - Doctrine handles parameterization
$qb->where('u.email = :email')
   ->setParameter('email', $email);

// BAD - SQL injection risk
$sql = "WHERE email = '$email'";

Sanitize Output

{# Twig auto-escapes by default - GOOD #}
{{ user_input }}

{# For trusted HTML only #}
{{ trusted_html|raw }}

Encrypt Sensitive Data

// Use password field type in config_schema
#[ORM\Column(type: 'string')]
private string $apiKey; // Automatically encrypted by PteroCA

Validate Webhooks

private function verifySignature(string $payload, string $signature): bool
{
    $secret = $this->pluginSettings->get('my-plugin', 'webhook_secret');
    $expectedSignature = hash_hmac('sha256', $payload, $secret);
    return hash_equals($expectedSignature, $signature);
}

Performance

Use Caching

public function getCacheKey(): ?string
{
    return 'my_widget_data_' . $this->userId;
}

public function getCacheTtl(): int
{
    return 300; // 5 minutes
}

Optimize Database Queries

// GOOD - Single query with join
$qb->select('u', 's')
   ->from(User::class, 'u')
   ->leftJoin('u.servers', 's');

// BAD - N+1 queries
foreach ($users as $user) {
    $servers = $user->getServers(); // Separate query each time
}

Add Database Indexes

#[ORM\Index(columns: ['user_id'], name: 'idx_user_id')]
#[ORM\Index(columns: ['created_at'], name: 'idx_created_at')]
class VisitLog
{
    // ...
}

Lazy-Load Heavy Services

public function __construct(
    private readonly ContainerInterface $container,
) {}

private function getHeavyService(): HeavyService
{
    return $this->container->get(HeavyService::class);
}

Minimize Asset Size

• Minify CSS/JS for production

• Optimize images (compress, WebP format)

• Use CDNs for common libraries

• Bundle and compress assets

Batch Operations

// Process in chunks to avoid memory issues
$batchSize = 100;
$items = $this->repository->findAll();

foreach (array_chunk($items, $batchSize) as $batch) {
    foreach ($batch as $item) {
        $this->process($item);
    }
    $this->entityManager->flush();
    $this->entityManager->clear();
}

Code Quality

Follow PSR-12 Coding Standards

<?php

declare(strict_types=1);

namespace Plugins\MyPlugin\Service;

final class MyService
{
    private const MAX_RETRIES = 3;

    public function __construct(
        private readonly LoggerInterface $logger,
    ) {
    }

    public function process(string $input): array
    {
        // Implementation
    }
}

Use Type Hints

// GOOD - Type hints everywhere
public function process(string $input): array
{
    return ['result' => $input];
}

// BAD - No type hints
public function process($input)
{
    return ['result' => $input];
}

Document Public Methods

/**
 * Process payment and return result
 *
 * @param float $amount Payment amount
 * @param string $currency Currency code (ISO 4217)
 * @return PaymentResult Result of payment processing
 * @throws PaymentException If payment fails
 */
public function processPayment(float $amount, string $currency): PaymentResult
{
    // Implementation
}

Handle Errors Gracefully

try {
    $result = $this->externalService->call();
} catch (ExternalServiceException $e) {
    $this->logger->error('Service call failed', [
        'error' => $e->getMessage()
    ]);

    // Return fallback instead of breaking
    return $this->defaultFallback();
}

Log Important Operations

$this->logger->info('Payment processed', [
    'user_id' => $userId,
    'amount' => $amount,
    'currency' => $currency,
    'provider' => $this->getIdentifier()
]);

Keep Classes Focused

// GOOD - Single responsibility
class PaymentProcessor
{
    public function process(Payment $payment): PaymentResult {}
}

class PaymentValidator
{
    public function validate(Payment $payment): bool {}
}

// BAD - Too many responsibilities
class PaymentManager
{
    public function process() {}
    public function validate() {}
    public function sendEmail() {}
    public function logToDatabase() {}
    public function generateReport() {}
}

Compatibility

Specify Version Constraints

{
    "pteroca": {
        "min": "0.6.0",
        "max": "1.0.0"
    }
}

Test with Minimum Version

Always test your plugin with the minimum PteroCA version you support.

Document Breaking Changes

In CHANGELOG.md:

## [2.0.0] - 2025-01-15

### Breaking Changes
- Removed deprecated `oldMethod()` - use `newMethod()` instead
- Changed payment provider interface signature
- Minimum PHP version is now 8.2

### Migration Guide
...

Provide Upgrade Guides

Help users migrate between major versions with clear upgrade documentation.

Plugin Structure

Organize by Feature

src/
├── Controller/
│   └── PaymentController.php
├── Service/
│   ├── PaymentProcessor.php
│   └── PaymentValidator.php
├── Entity/
│   └── Payment.php
└── Repository/
    └── PaymentRepository.php

Use Consistent Naming

• Classes: PascalCase

• Methods: camelCase

• Constants: UPPER_SNAKE_CASE

• Database tables: plg_prefix_table_name

Separate Concerns

• Controllers: Handle HTTP

• Services: Business logic

• Repositories: Data access

• Entities: Data models

Database

Use Migrations for Schema Changes

// GOOD - Migration
public function up(Schema $schema): void
{
    $this->addSql('CREATE TABLE ...');
}

// BAD - Creating tables in Bootstrap
public function initialize(): void
{
    // Don't create tables here!
}

Always Use Table Prefix

CREATE TABLE plg_my_plugin_data ...

Add Indexes for Performance

INDEX idx_user_id (user_id),
INDEX idx_created_at (created_at)

Handle DateTime Correctly

created_at DATETIME NOT NULL COMMENT '(DC2Type:datetime_immutable)'

User Experience

Provide Clear Error Messages

// GOOD
throw new InvalidArgumentException('API key must be at least 32 characters long');

// BAD
throw new Exception('Invalid input');

Use Translations

{# GOOD #}
{{ 'error.api_key_missing'|trans({}, 'plugin_my_plugin') }}

{# BAD #}
{{ 'API key is missing' }}

Show Progress for Long Operations

$this->io->progressStart(count($items));

foreach ($items as $item) {
    $this->processItem($item);
    $this->io->progressAdvance();
}

$this->io->progressFinish();

Validate Forms

$form->handleRequest($request);

if ($form->isSubmitted() && $form->isValid()) {
    // Process
} else {
    // Show validation errors
}

Testing

Write Tests

public function testProcessPayment(): void
{
    $processor = new PaymentProcessor();
    $result = $processor->process($payment);

    $this->assertEquals('success', $result->getStatus());
}

Test Edge Cases

• Empty input

• Invalid data

• Boundary values

• Error conditions

Use Meaningful Test Names

// GOOD
public function testThrowsExceptionWhenApiKeyIsMissing(): void

// BAD
public function test1(): void

Documentation

Document Public APIs

Every public method should have PHPDoc.

Provide README.md

Include in your plugin:

# My Plugin

Description of what the plugin does.

## Installation

1. Copy to plugins/my-plugin/
2. Enable: `php bin/console pteroca:plugin:enable my-plugin`

## Configuration

...

## Usage

...

Maintain CHANGELOG.md

Track all changes between versions.

Include Examples

Provide code examples in documentation.

Avoid Common Pitfalls

Don't Modify Core Files

Never edit PteroCA core code. Use events and services instead.

Don't Use Global State

// BAD
global $myVariable;

// GOOD
$this->myProperty

Don't Hardcode Paths

// BAD
'/var/www/pteroca/plugins/my-plugin/file.txt'

// GOOD
__DIR__ . '/../../file.txt'

Don't Skip Error Handling

Always handle potential exceptions, especially in:

• External API calls

• File operations

• Database queries

Related Guides

• Testing - Test your plugin thoroughly

• Security - Security guidelines

• Plugin Structure - Organization