Development Guidelines

Standards and best practices for developing qoliber Magento 2 extensions. All extensions must meet these requirements before release.

1. Code Quality

PHP_CodeSniffer

All extensions must pass PHP_CodeSniffer validation before every commit. We follow Magento's coding standards:

vendor/bin/phpcs --standard=Magento2 app/code/Qoliber/

Reference: mrm-commerce/magento-coding-standard-phpcs

PHPStan — Level 8

Code must achieve PHPStan level 8 compliance for maximum type safety. No exceptions.

vendor/bin/phpstan analyse --level=8 app/code/Qoliber/

Reference: bitExpert/phpstan-magento

2. Performance

Blackfire Profiling

All code undergoes profiling using Blackfire to identify and eliminate performance bottlenecks. Optimisations are driven by profiling data, not assumptions.

Key metrics we track:

• Wall time impact on category and product pages
• Database query count and duration
• Memory consumption under load

3. Compatibility

Magento Framework

All extensions must support:

Hyvä Themes

Full compatibility with Hyvä Themes is required. Templates, CSS, and JavaScript integrations must work seamlessly with both Luma and Hyvä.

ElasticSuite

Extensions that touch search or catalog must integrate with ElasticSuite. Thorough testing is required to prevent conflicts with ElasticSuite's indexing and query pipeline.

4. Event Handling & Class Overrides

Plugin-First Architecture

5. Scalability Testing

Every extension must be tested across three dataset sizes:

Performance and functionality must remain consistent across all sizes. Extensions that degrade at scale are not shipped.

6. Best Practices

Documentation

Comprehensive developer documentation is required for every extension:

• Installation and setup instructions
• Configuration reference (every admin field documented)
• Usage examples with screenshots
• Developer notes for customisation points

Modularity

Modular architecture is required. Separate concerns into distinct, reusable components:

• Business logic in Models/Services
• Data access in Repositories
• UI in ViewModels (not Blocks)
• API contracts via Api/ interfaces

Security

• Validate all user inputs and escape all outputs
• Use Magento's built-in CSRF protection
• Prevent SQL injection — always use parameterised queries
• Prevent XSS — use $escaper->escapeHtml() in templates
• Follow Magento Security Best Practices

Testing

• Unit tests for business logic
• Integration tests for database operations and API contracts
• Functional tests (MFTF) for complex UI workflows
• Use Magento's test framework for automation

Deployment

• CI/CD pipeline compatible
• No manual steps required during deployment
• Semantic versioning with clear release notes
• All changes tracked in CHANGELOG.md

7. Distribution

Paid Extensions — Private Packagist

Paid extensions are distributed through Private Packagist for controlled access and licence management. Customers receive Composer credentials tied to their licence.

Free Extensions — Public Packagist

Free extensions are published on public Packagist with:

• Proper composer.json metadata
• Semantic versioning
• MIT licence
• GitHub repository with issue tracking enabled