Statamic Image Cropper Laravel Package

Getting Started

• Install via Composer: composer require tv2regionerne/statamic-image-cropper. Statamic auto-discovers the service provider; no manual registration is normally required. If the package ships a config file, publish it with php artisan vendor:publish --tag=statamic-image-cropper-config and review container/aspect-ratio options. Clear caches afterwards: php please cache:clear and php artisan view:clear.
• First place to look: the README’s fieldtype section, then vendor/tv2regionerne/statamic-image-cropper/src to confirm the exact fieldtype handle (likely image_cropper) and the shape of saved data—typically an asset reference plus crop coordinates. Check the Vue component under resources/js if the CP behavior is unclear.
• First use case: a “hero image” field that must always be 16:9. Add it to a blueprint in YAML or the CP:

hero_image:
  type: image_cropper
  display: Hero Image
  container: assets
  aspect_ratio: 16/9

Editors select an asset and crop it in the control panel. In Antlers, use the field’s asset and its crop data with Glide—e.g., {{ hero_image:url }} with width, height, and fit="crop" parameters, or the package’s provided tag/modifier. Confirm the exact Antlers syntax in the README; the key is that the crop rectangle is available so the front-end crop matches the editorial preview.

Implementation Patterns

• One field per crop role. Create hero_image, card_image, thumbnail_image, etc., each with a fixed aspect ratio and container. This keeps the editorial UI simple and prevents accidental mismatched crops.
• Pair with metadata fields. Keep hero_image_alt as a separate text field; the cropper owns visual crop, not accessibility text. Output <img src="{{ hero_image:url ... }}" alt="{{ hero_image_alt }}">.
• Responsive images. Reuse the same crop rectangle across breakpoints via Glide or Statamic’s srcset tag. Example pattern:

<img
  src="{{ hero_image:url width="1200" height="675" fit="crop" }}"
  srcset="
    {{ hero_image:url width="600" height="338" fit="crop" }} 600w,
    {{ hero_image:url width="1200" height="675" fit="crop" }} 1200w
  "
  alt="{{ hero_image_alt }}">

• Multiple crops of one asset. Use separate fields (e.g., hero_crop, card_crop) pointing at the same asset container, or a Replicator/Grid with a crop preset selector if the package supports configurable presets. Avoid storing raw crop JSON in a text field—you lose validation and CP UX.
• Fallback handling. If the field is empty, fall back to a default asset or a CSS placeholder: {{ if hero_image }}{{ ... }}{{ else }}<div class="placeholder"></div>{{ /if }}.
• Integration tip: Commit blueprint YAML so field configurations are repeatable. If the package provides a config file, define allowed aspect ratios and containers there rather than duplicating them across blueprints.

Gotchas and Tips

• Low adoption risk. With 10 stars and zero dependents, treat the package as unproven. Read the source before relying on it; test against your Statamic version (especially Statamic 5) in staging. If the Composer constraint blocks an upgrade, fork or vendor the fieldtype.
• Data shape matters. Crop data is stored in front matter. Inspect a saved entry’s YAML to see exactly what is persisted—pixel coordinates vs. percentages, asset path vs. ID. Build template helpers around that shape; don’t assume Antlers syntax if the README is thin.
• Glide cache and crop changes. Changing a crop must change the generated Glide URL or the cached image will not update. Look for a cache-busting parameter (e.g., crop hash) in the package’s URL builder, or append crop data to the Glide parameters yourself. Clear storage/statamic/glide (or your configured cache) when debugging.
• Aspect-ratio mismatch. The CP crop preview and front-end Glide fit="crop" dimensions must agree. Cropping to 16:9 but requesting 1200×800 without fit="crop" will distort or letterbox the image. Centralize dimensions in a config or partial.
• Asset lifecycle. Moving or renaming an asset can break stored crop references. If your asset container allows reorganization, consider locking it or adding validation that the referenced asset still exists.
• Debugging steps. Check the browser console for Vue errors in the CP; inspect the network request when saving a crop. In the backend, add Log::debug() in the fieldtype’s preProcess/process methods (if you fork) or use Statamic’s debug tools. The fieldtype class and Vue component are under vendor/tv2regionerne/statamic-image-cropper/src and resources/js.
• Extension points. Publish the config and views if available. For custom behavior (e.g., storing crops per breakpoint), extend the fieldtype class or create a custom tag that reads the crop array and builds Glide URLs. With a small package, contributing upstream may be faster than forking, but keep a local patch if the maintainer is inactive.