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
インストール
composer require 'drupal/crop:8.x-2.5'
composer require 'drupal/crop:8.x-2.2'
概要
Crop APIモジュールは、Drupalにおける画像クロッピングの基盤APIを提供します。画像のクロッピング情報（位置、サイズ、アンカー座標）を保存する「Crop」というコンテンツエンティティタイプと、オプションのアスペクト比制約やサイズ制限を持つ異なるタイプのクロップを定義する「Crop Type」という設定エンティティタイプを確立します。
このモジュールはAPIレイヤーとして設計されており、単独ではユーザー向けのクロッピングインターフェースを提供しません。代わりに、Image Widget CropやFocal PointなどのUIモジュールが完全なクロッピングソリューションを提供するために利用できるデータストレージ、サービス、フックを提供します。
このモジュールには、画像派生物を生成する際に保存されたクロップデータを適用するために画像スタイルに追加できる「Manual crop」画像エフェクトが含まれています。また、画像を含む異なるエンティティタイプ（File、Media）との統合を可能にするエンティティプロバイダー用の拡張可能なプラグインシステムも提供します。
主要なアーキテクチャ機能には、クロップデータ変更時の画像派生物の自動フラッシュ、ハッシュパラメータによるURLベースのキャッシュ無効化、イベントシステムを通じた自動クロッププロバイダーのサポート、コンテンツステージングシナリオ向けのDrupalのデフォルトコンテンツエクスポーターとの統合が含まれます。
Features
- 位置（x、y中心座標）、サイズ（幅、高さ）、アンカー（左上角）、およびソースエンティティへの参照を持つ画像クロップデータを保存するための「Crop」コンテンツエンティティタイプを定義
- オプションのアスペクト比（例：16:9）、ソフトリミット（クロップが小さい場合に警告）、ハードリミット（最小クロップサイズ）を持つ異なるクロップタイプを作成するための「CropType」設定エンティティを定義
- 画像スタイルで使用するための「Manual crop」画像エフェクトプラグインを提供し、保存されたクロップデータを画像に適用
- FileおよびMediaエンティティを標準でサポートし、カスタムエンティティタイプ向けに拡張可能なプラグインベースのエンティティプロバイダーシステム
- 手動クロップが存在しない場合に他のモジュールがフォールバッククロッピングを提供できる自動クロッププロバイダー用のイベントシステム
- Cropエンティティが保存されたときに影響を受ける画像スタイル派生物の自動フラッシュ（設定で構成可能）
- クロップ変更時のキャッシュ無効化のためのURLハッシュパラメータ追加、CDN/プロキシキャッシュバスティングを有効化
- クロッピングに使用する画像フィールドを指定するためのMediaタイプ設定との統合
- Cropエンティティの適切なインポート/エクスポートのためのDrupal Coreのデフォルトコンテンツエクスポーター（Drupal 11以降）との統合
- 完全なリビジョン履歴追跡を備えたCropエンティティのリビジョンサポート
- 言語ごとに異なるクロップを許可するCropエンティティの翻訳サポート
- 効率的なクロップルックアップのためのuriおよびtypeフィールドのデータベースインデックス最適化
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.
権限 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