Crop API
Provides storage and API for image crops. This module defines the underlying entity structure and API that UI modules can use to provide image cropping functionality.
crop
Install
composer require 'drupal/crop:8.x-2.5'
composer require 'drupal/crop:8.x-2.2'
Overview
The Crop API module provides a foundational API for image cropping in Drupal. It establishes a content entity type called "Crop" that stores cropping information (position, size, anchor coordinates) for images, along with a configuration entity type called "Crop Type" that defines different types of crops with optional aspect ratio constraints and size limits.
This module is designed as an API layer and does not provide a user-facing cropping interface on its own. Instead, it provides the data storage, services, and hooks that UI modules like Image Widget Crop or Focal Point can utilize to offer complete cropping solutions.
The module includes a "Manual crop" image effect that can be added to image styles to apply stored crop data when generating image derivatives. It also provides an extensible plugin system for entity providers, enabling integration with different entity types (File, Media) that contain images.
Key architectural features include automatic flushing of image derivatives when crop data changes, URL-based cache busting via hash parameters, support for automatic crop providers through an event system, and integration with Drupal's default content exporter for content staging scenarios.
Features
- Defines a 'Crop' content entity type for storing image crop data with position (x, y center coordinates), size (width, height), anchor (top-left corner), and reference to the source entity
- Defines a 'CropType' configuration entity for creating different crop types with optional aspect ratio (e.g., 16:9), soft limits (warning if crop is smaller), and hard limits (minimum crop size)
- Provides 'Manual crop' image effect plugin for use in image styles that applies stored crop data to images
- Plugin-based entity provider system supporting File and Media entities out of the box, extensible for custom entity types
- Event system for automatic crop providers allowing other modules to provide fallback cropping when manual crops don't exist
- Automatic flushing of affected image style derivatives when crop entities are saved (configurable via settings)
- URL hash parameter appending for cache invalidation when crops change, enabling CDN/proxy cache busting
- Integration with Media type configuration to specify which image field should be used for cropping
- Integration with Drupal core's default content exporter (Drupal 11+) for proper import/export of crop entities
- Revision support for crop entities with full revision history tracking
- Translation support for crop entities allowing different crops per language
- Database index optimization on uri and type fields for efficient crop lookups
Use Cases
Responsive image cropping
Create different crop types for various aspect ratios needed across your site (e.g., 16:9 for hero images, 1:1 for thumbnails, 4:3 for article images). Configure image styles with the Manual crop effect for each crop type. Use a UI module to allow content editors to set crops for each image. The same source image can have different crops for different display contexts.
Media library with cropping
Configure your Media types to specify which image field should be used for cropping. When editors add or edit Media items, they can define crops that will be applied consistently wherever that Media item is displayed. This ensures brand consistency across the site.
Decoupled/headless architecture
For sites using cloud storage (like S3) with CDN delivery, disable automatic derivative flushing by setting flush_derivative_images to false. Generate image derivatives through a separate build process and push to your cloud storage. Crop API will still append hash parameters to URLs for cache invalidation.
Automatic fallback cropping
Subscribe to the crop.automatic_crop event to provide automatic cropping when editors haven't set a manual crop. For example, use face detection to automatically center crops on faces, or use focal point data to create smart crops that preserve the important parts of images.
Content staging with crops
When using Drupal 11's default content exporter, crop entities are automatically handled during export/import. Crops are exported with UUID references to their source entities and correctly re-linked during import, making content staging workflows seamless.
Multi-language image cropping
Since crop entities are translatable, different crops can be defined for different languages. This is useful when images need different cropping for different language versions (e.g., images containing text that varies by language).
Tips
- Always install a UI module (like Image Widget Crop or Focal Point) alongside Crop API - the API module alone does not provide cropping interface
- Use soft limits to guide editors toward minimum quality crops while still allowing smaller crops when necessary
- Use hard limits when you have strict minimum size requirements that must be enforced
- The aspect ratio setting is optional - leave it empty for free-form cropping where any proportion is acceptable
- When debugging crop issues, check the crop_field_data database table to verify crop entities are being created with correct values
- Use the 'Flush' operation carefully - it permanently deletes all crop data for a crop type
- For better performance with many crops, the module creates a database index on (uri, type) columns
Technical Details
Admin Pages 5
/admin/config/media/crop
Lists all configured crop types in the system. Displays the name, description, aspect ratio, and which image styles use each crop type. Provides operations to edit, delete, or flush crops for each type.
/admin/config/media/crop/add
Form to create a new crop type with configurable name, machine name, description, aspect ratio, and size limits.
/admin/config/media/crop/manage/{crop_type}
Form to modify an existing crop type's settings. The machine name cannot be changed after creation.
/admin/config/media/crop/manage/{crop_type}/delete
Confirmation form for deleting a crop type. The crop type can only be deleted if there are no crop entities using it.
/admin/config/media/crop/manage/{crop_type}/flush
Confirmation form for deleting all crop entities of a specific crop type. This is useful when you want to remove all crop data for a particular type without deleting the type definition itself.
Permissions 2
Hooks 1
hook_crop_entity_provider_info_alter
Allows modules to alter the information provided by CropEntityProvider plugins. Can be used to modify labels, descriptions, or other properties of entity provider plugins.
Troubleshooting 5
Ensure flush_derivative_images is set to true in crop.settings. Clear all caches and check that the crop entity is properly saving. For cloud storage setups, you may need to regenerate derivatives manually.
Verify that: 1) The image style has the 'Manual crop' effect with the correct crop type selected, 2) A crop entity exists for the image URI and crop type, 3) The crop entity has valid position and size values.
Add a file or image field to your Media type first. The crop configuration fieldset only appears when there are valid file/image fields on the bundle.
You must first delete or flush all crop entities of that type. Use the 'Flush' operation to remove all crops, then delete the type.
Ensure aspect ratio is in W:H format with positive integers only (e.g., 16:9, 4:3, 1:1). Do not include decimals, percentages, or other formats.
Security Notes 3
- The module uses access checks when querying crop entities
- Entity provider plugins should validate entity types and field values before returning URIs
- Crop data is stored per-URI and could potentially expose file system structure through the uri field