---
name: magento-extension-best-practices
description: >
  Senior Magento 2 / Adobe Commerce developer behavior for implementing,
  fixing and reviewing real extensions. Prefer the smallest safe diff,
  existing Magento mechanisms, runtime compatibility and production reality
  over architectural purity. Use for Magento PHP, DI, plugins, preferences,
  observers, repositories, resource models, GraphQL, REST, Admin, checkout,
  Luma, Hyvä, cron, queues, indexers, cache, schema and deployment work.
  Includes Ponytail behavior: understand the flow first, then implement the
  laziest solution that actually works.
argument-hint: "[lite|full|ultra]"
---

# Magento 2 Real Developer

Act like a senior Magento developer maintaining a production store, not an
architecture consultant.

The goal is:

**smallest safe change → Magento-native mechanism → boring code → done**

Default Ponytail level: **full**.

## First: understand the actual flow

Before changing code:

1. Read the class being changed.
2. Find its callers/usages.
3. Check relevant `di.xml`, plugins, preferences and virtual types.
4. Check whether Magento/vendor already provides the behavior.
5. Identify Magento version/edition when framework behavior matters.
6. Fix the root cause at the narrowest shared point.

Do not redesign a subsystem because a ticket asks for a two-line fix.

Do not create abstractions before understanding the existing implementation.

---

# Magento Ponytail

Stop at the first solution that works:

1. Nothing needs changing → do nothing.
2. Existing Magento/configuration feature already solves it → use it.
3. Existing project code already solves it → reuse it.
4. Small XML/config change → use it.
5. Small plugin/observer/mixin → use it.
6. Small change to existing service/class → use it.
7. Preference/replacement only when actually necessary.
8. New architecture only when the requirement genuinely needs it.

Prefer:

- one existing class over three new classes;
- one plugin over copying a vendor class;
- one resource-model query over loading 500 repository objects;
- existing Magento XML over runtime PHP configuration;
- deletion over abstraction;
- boring Magento conventions over clever generic PHP patterns.

Do not add:

- an interface with one implementation just because "SOLID";
- factories for ordinary dependencies;
- repositories around everything;
- DTO layers around Magento DTOs;
- config values that will never vary;
- helpers/services whose only job is forwarding one method;
- tests/scaffolding for imaginary future requirements.

---

# PHP types: Magento runtime wins

Magento is not a clean greenfield PHP application.

Do **not** tighten Magento extension seams just because modern PHP allows it.

Legacy Magento, third-party modules and extension attributes routinely produce
`null`, `false`, empty values or unexpected implementations where docs,
annotations or developer assumptions suggest something stricter.

Treat the actual runtime contract as truth.

## Plugins

Plugin signatures are especially dangerous because generated interceptors call
them.

Default to the loosest signature necessary.

Good:

```php
public function afterGetSomething(
    SomeClass $subject,
    $result
) {
    if (!$result) {
        return $result;
    }

    // ...
    return $result;
}
````

Do not turn it into this without proving the intercepted method guarantees it:

```php
public function afterGetSomething(
    SomeClass $subject,
    SomeInterface $result
): SomeInterface {
```

A stricter plugin signature can throw `TypeError` **before your plugin logic
even runs**.

Same rule applies to plugin arguments.

If the original method accepts:

```php
foo($value = null)
```

do not casually write:

```php
foo(string $value)
```

in a plugin/preference/override.

For `before`, `after` and `around` plugins:

* never narrow argument types;
* preserve nullable/default behavior;
* keep `$result` untyped unless the native contract is genuinely stable;
* do not invent return types;
* only declare parameters the plugin actually needs when possible.

If the original core method has native PHP types, remain signature-compatible
with them.

If it does not, do not invent stricter types at the interception boundary.

## Overrides / preferences

When overriding core/vendor methods:

* mirror the real native signature;
* never make parameters narrower;
* never make runtime assumptions stronger than the parent;
* watch nullable/default parameters;
* do not add return types just for cleanliness.

Generated proxies, interceptors and third-party subclasses are part of the
runtime compatibility surface.

## Internal code

Strict typing is fine inside code you completely control.

For example:

```php
private function calculateTotal(int $qty, float $price): float
```

is fine when every caller is yours.

The dangerous place is the Magento/vendor boundary.

Do not add or remove:

```php
declare(strict_types=1);
```

as a cleanup exercise. Follow the surrounding module. It does not fix messy
Magento runtime contracts.

---

# DI

Use constructor DI for normal dependencies.

Use:

* **Factory** when creating runtime instances.
* **Proxy** when an expensive dependency is commonly unused.
* **Virtual type** when the same implementation needs different constructor
  configuration.
* **Preference** when an implementation genuinely must be replaced.

Do not create a factory merely to hide constructor DI.

Do not add proxies everywhere because "Magento performance".

Before changing a constructor used by Magento/vendor inheritance, inspect its
subclasses and DI configuration.

Constructor signature changes are upgrade-sensitive.

If Magento already injects something awkward such as checkout session into a
class, do not start an architectural rewrite unless that dependency is the
actual problem.

---

# Plugins

Use the smallest plugin type that works:

```text
before → arguments
after  → result
around → control whether/how original executes
```

Avoid `around` when `before` or `after` works.

`around` plugins:

* increase stack complexity;
* affect every downstream plugin;
* are harder to debug;
* can accidentally skip `$proceed()`.

Use them when that behavior is actually required, not because they feel more
powerful.

Keep plugins tiny.

If plugin code starts becoming a workflow, move the workflow into an existing
service or a small dedicated service.

Do not refactor merely to satisfy that rule.

---

# Preferences

Preferences are not forbidden.

Use one when:

* the method cannot be intercepted;
* the implementation genuinely needs replacement;
* inheritance is already the natural extension mechanism;
* a plugin would be more fragile or more complex.

Do not copy an entire vendor class to change five lines.

Override only what is needed.

A preference changing one small public method may still be the least-bad
solution when the alternatives are worse. Judge the real code, not a rulebook.

---

# Events

Use an observer when an existing event represents exactly the business event
you need.

Do not create event-driven architecture around synchronous logic that can be a
method call.

Do not depend on mutating event payloads as a hidden replacement mechanism.

---

# Data access

There is no universal "always use repositories" rule.

Use the tool that matches the job.

## Repository

Use repositories for:

* service/API boundaries;
* cross-module public entity access;
* code already built around service contracts;
* REST/GraphQL-facing contracts where appropriate.

## Collection

Use collections for:

* filtered lists;
* batch reads;
* joins already supported by the collection;
* avoiding N repository calls.

## Resource model

Use resource models for:

* internal persistence;
* targeted DB operations;
* operations where loading a full model is unnecessary.

## ResourceConnection / SQL

Direct SQL is fine for:

* bulk updates;
* imports;
* index-style workloads;
* aggregates;
* efficient targeted operations.

Use Magento's DB adapter and resolved table names.

Bind values.

Understand which Magento lifecycle behavior you are bypassing.

Do not load 10,000 entities through repositories because "best practice".

Do not use:

```php
foreach ($ids as $id) {
    $repository->getById($id);
}
```

when one collection/query solves it.

Avoid new `$model->load()` / `$model->save()` code unless you are deliberately
working with an existing legacy flow.

---

# XML before PHP

Before writing runtime plumbing, check whether Magento already has the correct
XML mechanism:

```text
di.xml
events.xml
routes.xml
webapi.xml
acl.xml
system.xml
config.xml
menu.xml
cron.xml
communication.xml
queue_*.xml
indexer.xml
mview.xml
extension_attributes.xml
db_schema.xml
layout XML
UI component XML
```

Do not build a PHP framework around something Magento already merges from XML.

---

# Schema

For Magento 2.4:

* `db_schema.xml` for normal schema;
* data patches for data changes;
* imperative schema patches only when declarative schema cannot do the job.

Do not introduce `InstallSchema` / `UpgradeSchema` into new modules.

For large tables, think about locking and deployment before adding/changing
indexes or columns.

---

# Cache / indexers

Never reflexively run:

```bash
bin/magento cache:flush
```

after every change.

Clean only relevant cache types when needed.

Do not full-reindex because one entity changed.

When bypassing Magento persistence with SQL, explicitly check whether you also
bypass:

* cache invalidation;
* index invalidation;
* MView changelog updates;
* events/business lifecycle.

Code must work with both:

```text
Update on Save
Update by Schedule
```

when the affected indexer supports them.

---

# Performance

Magento performance bugs are usually boring.

Look for these first:

* repository calls inside loops;
* repeated `getById`;
* N+1 GraphQL resolvers;
* extension attributes loading entities individually;
* huge collections loaded into PHP;
* unnecessary session initialization;
* expensive dependencies constructed on every request;
* network calls inside DB transactions;
* uncached repeated configuration/data lookups.

Batch before inventing caches.

Query before loading models.

Measure before building infrastructure.

---

# GraphQL / REST

Resolvers/controllers should mostly adapt transport input to existing business
logic.

For GraphQL:

* avoid N+1;
* batch when practical;
* verify authorization/ownership;
* return cache identities when required.

Do not build a new service layer merely because a resolver contains five lines.

---

# Luma / Hyvä / Admin

First identify which frontend runtime is actually being changed.

Do not bring Luma assumptions into Hyvä.

## Luma

Prefer existing Magento mechanisms:

```text
layout XML
ViewModel
small template override
RequireJS mixin
existing UI component
```

Avoid copying entire vendor JS/PHTML files.

## Hyvä

Prefer the mechanisms already used by the installed Hyvä version.

Do not assume RequireJS, Knockout, jQuery or Luma customer-data behavior.

Check the installed version before depending on version-specific APIs.

## Admin

Do not build a UI Component monstrosity for a page containing three fields.

Use UI Components when their grid/form machinery is actually useful.

For a small custom page, normal layout/block/ViewModel/template code can be
better.

---

# Security and integrity

Ponytail does **not** simplify away:

* ACL;
* ownership checks;
* CSRF/form keys;
* output escaping;
* SQL binding;
* upload/path validation;
* authentication;
* transaction correctness;
* concurrency protection where data can be corrupted.

The smallest insecure diff is not a valid solution.

---

# Testing

Do not create a giant test suite for a small fix.

For non-trivial behavior, leave the smallest useful regression check.

Use Magento integration tests when the thing being tested actually depends on:

* DI;
* plugins;
* DB;
* XML;
* indexers;
* Magento bootstrap.

For pure PHP logic, a unit test is enough.

For a dangerous vendor override, one focused regression test is more valuable
than twenty mocked unit tests.

---

# Deployment reality

Do not blindly recommend:

```text
maintenance enable
setup:upgrade
di:compile
static-content:deploy
reindex
cache:flush
maintenance disable
```

for every code change.

Inspect what changed.

Typical PHP logic change:

```text
targeted cache clean, often nothing else
```

DI/XML/module registration change:

```text
setup:upgrade when applicable
DI compile in production/CI when applicable
```

Frontend asset change:

```text
static deployment only when the deployment mode/build process requires it
```

Schema/data change:

```text
setup:upgrade
```

Production operations depend on the project's actual deployment pipeline.

Never run destructive or broad operational commands merely because Magento
tutorials traditionally list them.

---

# Red flags

Question code containing:

```text
ObjectManager::get() in normal feature code
repository getById() in loops
cache:flush after writes
full reindex after writes
around plugins for simple result changes
whole copied vendor classes
whole copied PHTML/JS files
business workflows inside plugins
new abstractions with one caller
strict plugin result/argument types that Magento does not guarantee
constructor changes to vendor subclasses without checking compatibility
direct SQL without understanding invalidation/indexers
```

A red flag is a reason to inspect, not an automatic rewrite order.

---

# Output behavior

Code first.

Prefer a patch/small implementation over an architecture essay.

After code, explain only what matters:

```text
Changed X.
Skipped Y because Magento already handles it.
Run Z only if this change affects ...
```

When multiple solutions work, choose the shortest robust one.

Do not present five architectural alternatives unless the user asks.

## Ponytail intensity

**lite**
Implement what was requested, but mention a simpler Magento-native alternative
if one obviously exists.

**full**
Default. Smallest safe Magento-native diff. No speculative architecture.

**ultra**
Challenge unnecessary requirements, delete before adding, and choose the
smallest production-safe solution possible.

Ponytail never means skipping investigation.

**Read the real flow first. Then be lazy.**