pimcore/pimcore-studio-backend-checklist

Architecture Context

The StudioBackendBundle uses a layered architecture: Controllers (HTTP only) -> Services (business logic) -> Hydrators (DTO creation). Events provide extension points. All APIs are OpenAPI-documented.

Use this checklist before considering any migration or new Studio feature complete.

---

Anti-Patterns to Avoid

1. Passing nullable values to PHP filesystem functions -- in PHP 8.x with declare(strict_types=1), functions like is_file(), filesize(), unlink() throw TypeError when passed null. Always null-check before calling:

   // BAD -- crashes with TypeError when $path is null
   if (is_file($path)) { ... }
   
   // GOOD -- guard against null
   if ($path === null || !is_file($path)) { return []; }
   
   // GOOD -- positive check
   if ($path !== null && is_file($path)) { ... }
   

2. Assuming non-standard endpoints should be migrated -- when encountering endpoints that break Studio conventions (e.g., public-facing webhooks with Bearer token auth, different route prefixes, non-admin endpoints), always ask the user for a decision before proceeding rather than assuming they should be migrated.

3. Redundant runtime type checks after typed constructor params -- if a constructor already enforces a type (e.g., array $doctrineConnections), don't add runtime is_array() or similar checks. The type system handles it.

4. Static calls to Pimcore classes outside the bundle -- never use static calls like Pimcore\Tool::getValidLanguages(), Pimcore\Model\Asset::getById(), or any other static call to a Pimcore class that lives outside the current bundle. Always inject the corresponding resolver interface from Pimcore\Bundle\StaticResolverBundle instead. Third-party library static calls are not affected by this rule.

5. Using raw Request to extract query or body parameters -- never use $request->query->get(), $request->request->get(), or $request->get() in controllers. Always define a DTO class and use #[MapQueryString] (for GET) or #[MapRequestPayload] (for POST/PUT). The only exception is file uploads ($request->files->get('file')). If you encounter a situation where a DTO seems impossible, ask the user before proceeding with raw Request access.

---

Testing Checklist (34 Points)

Before considering any migration or new feature complete, verify:

Controllers

1. Controllers: final class, @internal, extends AbstractApiController.
2. Controllers: no business logic, permission checks, or vendor calls.
3. Monolithic controllers: split into one-action-per-controller in subdirectories.
4. Route priorities: priority: 10 on static routes conflicting with wildcards.

Services & Hydrators

5. Services/hydrators: final readonly class with @internal.
6. Permission checks: present in every service method that takes a config name.
7. File cleanup: uses try/finally pattern.
8. Non-HTTP exceptions: caught and converted to Studio API exceptions in services.
9. Null sort params: null-checked before building sort arrays.
10. Static calls: no static calls to Pimcore classes outside the bundle -- replaced with injected StaticResolverBundle resolver interfaces (third-party library static calls are exempt).
11. Container params: converted from $this->getParameter() to constructor injection with DI wiring.

DTOs & Events

12. Response DTOs: implements AdditionalAttributesInterface with AdditionalAttributesTrait.
13. Response DTOs: each has a corresponding event class.
14. Events: dispatched before returning every response DTO.
15. OpenAPI arrays: every type: 'array' has items.

Parameter Binding

16. Parameter binding: all GET query params use #[MapQueryString] with a DTO -- no raw $request->query->get().
17. Parameter binding: all POST/PUT body params use #[MapRequestPayload] with a DTO -- no raw $request->request->get().
18. Query DTOs: final readonly class, all properties have defaults, validation in getters not constructors.
19. Query DTOs: controller signature defaults to new SomeParameters() for optional query strings.

Code Style

20. @throws: on interfaces only (exception: trait methods).
21. @throws: short class names with proper use imports.
22. @throws: documents all throwable exceptions including Exception.
23. @throws types: reference Studio API exceptions, not generic PHP exceptions.
24. Imports: no unused imports.
25. Named arguments: only when skipping positional parameters.
26. FQCNs: none in code or PHPDoc -- everything via use imports.
27. Line length: max 120 chars. No exceptions.
28. Traits: @internal, @property for using-class properties, @throws on methods directly.
29. Nullable paths: guarded before is_file(), filesize(), etc.

Endpoints

30. Void endpoints: return new Response(), #[SuccessResponse] omits content.
31. Upload endpoints: validate instanceof UploadedFile, check size, include MAX_FILE_SIZE_EXCEEDED.

Configuration

32. DI config: studio_backend.yaml has bindings for all new interfaces.
33. Routing config: studio_routing.yaml exists and points to correct controller directory.
34. Translation strings: added for all new controller OpenAPI keys.

---

Reference: StudioBackendBundle Base Classes

| Class | Purpose | |-------|---------| | AbstractApiController | Base controller with jsonResponse() helper. Injects SerializerInterface. | | AbstractPreResponseEvent | Base event for pre-response extension. Takes AdditionalAttributesInterface. | | AdditionalAttributesInterface | Contract for DTOs that support runtime extension via key-value attributes. | | AdditionalAttributesTrait | Default implementation of AdditionalAttributesInterface. | | SecurityServiceInterface | getCurrentUser() to resolve the authenticated user. |

Studio API Exception Classes

All in namespace Pimcore\Bundle\StudioBackendBundle\Exception\Api\ unless noted.

| Exception Class | HTTP Code | Use Case | Constructor | |---|---|---|---| | NotFoundException | 404 | Entity not found | new NotFoundException(type: 'entity', id: $id, parameter: 'id', previous: $e) | | ForbiddenException | 403 | Permission denied | new ForbiddenException(sprintf('Access denied to "%s"', $name)) | | ConflictException | 409 | Optimistic locking, resource state conflicts | new ConflictException($message) | | EnvironmentException | 500 | Server/environment errors (intentional 500) | new EnvironmentException($message) | | InvalidArgumentException | 422 | Invalid input, validation failures | new InvalidArgumentException(message: $msg, previous: $e) | | MaxFileSizeExceededException | 413 | File too large | new MaxFileSizeExceededException($maxSize) | | NotFoundHttpException (Symfony) | 404 | Alternative to NotFoundException | new NotFoundHttpException($message) |