Getting Started

Install with Composer and confirm you are on PHP 8.1+; v0.6.0’s headline feature is attribute-based crop definitions. Pin the version ("vendor/package": "0.6.0") because this is still pre-1.0.
Start with the README section for the Croppable annotation, then open the attribute class in the package source (often under src/Attributes). That is the fastest way to learn the accepted arguments, targets, and namespace.
First use case: annotate an Eloquent model property or a small DTO with #[Croppable(...)] to declare crop dimensions or ratios, then call the package’s crop/resolve method from an upload controller. This replaces hard-coded crop arrays with declarative metadata.
If you are not ready to adopt attributes, keep using the package’s config/array API. The annotation is additive, not a forced migration.
Publish any package config (php artisan vendor:publish) before customizing defaults so future upgrades do not overwrite your settings.

Implementation Patterns

Declarative presets on models: put #[Croppable] on fields such as avatar or cover, then resolve them through the package’s resolver in a service class. Keep controllers thin and test the resolved presets directly.
Upload flow: validate the file plus crop coordinates in a FormRequest, store the original, then dispatch a queued job that applies the Croppable preset. Return the cropped path from the job rather than blocking the request.
User-driven crops: persist the user’s selected crop box in the database and merge it with annotation defaults at runtime. Annotations are good for defaults and presets, not per-record state.
Testing: use Storage::fake() and assert resulting image dimensions with getimagesize() or Intervention Image. Add a reflection-based test that reads the attribute so typos in preset names fail in CI.
Integration: if the package delegates to Intervention Image, keep the GD/Imagick driver consistent between local and production. Use the annotation for dimensions and ratios, not for driver-specific options.
Queue long-running crops with afterCommit() so jobs do not run before the model or file record exists. This matters when the crop preset depends on a newly created record.

v0.6.0 is pre-1.0. Pin the exact version and read the changelog before upgrading; attribute signatures and resolver behavior are especially likely to change.
Attributes are PHP 8+ only. On PHP 7.x, or when reflection/opcache caches are stale, the annotation may appear to be ignored. Clear caches after changing annotations.
Check the attribute’s target flags. If #[Croppable] only allows properties, placing it on a method or class will not be read. A missing use statement for the attribute class is a common silent failure.
If the package caches resolved crop metadata, changing an annotation without clearing that cache can leave old dimensions in place. Look for a cache key or artisan command in the package.
Debug by dumping the resolved crop config from the package’s resolver or service, then verify the image driver and file permissions. Many “annotation not working” reports are actually driver or path errors.
Extension points: publish the config to override default crop behavior, and bind a custom resolver or calculator in a service provider if the package exposes one. Keep custom logic out of the attribute itself so it stays declarative.
Do not conflate annotation defaults with persisted user crops. Store user crop coordinates in the database and apply them after resolving the annotation, otherwise edits will be lost on the next deploy.