{"record":{"id":"6e878b2c4cfc7ec3","repo":"Intervention/image","slug":"value-for-argument-disposal-method-method-must","errorCode":null,"errorMessage":"Value for argument disposal method \"$method\" must be 0, 1, 2 or 3","messagePattern":"Value for argument disposal method \"\\$method\" must be 0, 1, 2 or 3","errorType":"exception","errorClass":"InvalidArgumentException","httpStatus":null,"severity":"error","filePath":"src/Drivers/Imagick/Frame.php","lineNumber":160,"sourceCode":"        try {\n            return $this->native->getImageDispose();\n        } catch (ImagickException $e) {\n            throw new DriverException('Failed to get frame disposal method', previous: $e);\n        }\n    }\n\n    /**\n     * {@inheritdoc}\n     *\n     * @see DriverInterface::setDisposalMethod()\n     *\n     * @throws InvalidArgumentException\n     * @throws DriverException\n     */\n    public function setDisposalMethod(int $method): FrameInterface\n    {\n        if (!in_array($method, [0, 1, 2, 3])) {\n            throw new InvalidArgumentException('Value for argument disposal method \"$method\" must be 0, 1, 2 or 3');\n        }\n\n        try {\n            $this->native->setImageDispose($method);\n        } catch (ImagickException $e) {\n            throw new DriverException('Failed to set frame disposal method', previous: $e);\n        }\n\n        return $this;\n    }\n\n    /**\n     * {@inheritdoc}\n     *\n     * @see DriverInterface::setOffset()\n     *\n     * @throws DriverException\n     */","sourceCodeStart":142,"sourceCodeEnd":178,"githubUrl":"https://github.com/Intervention/image/blob/5598b9e39751c34afc5cdee84abef77f92c26f68/src/Drivers/Imagick/Frame.php#L142-L178","documentation":"Thrown by Frame::setDisposalMethod() when the integer passed is not one of 0, 1, 2 or 3. These values map to ImageMagick disposal constants: 0 = undefined, 1 = none, 2 = background, 3 = previous. It is a pure input-validation error (InvalidArgumentException) raised before any native call is made, so nothing has been modified when it fires.","triggerScenarios":"Calling setDisposalMethod() (directly or via animation helpers) with a value outside the whitelist, e.g. 4+ taken from newer ImageMagick disposal constants (DISPOSE_BLOCK etc.) or from external metadata/API payloads. Passing user input cast from a string like 'background' via intval() (which yields 0 only by luck) or an unvalidated query parameter.","commonSituations":"Porting code that used raw Imagick constants such as Imagick::DISPOSE_BLOCK (value 7) or Imagick::DISPOSE_BREAK (4); feeding disposal values from an animation JSON config or database column without validation; off-by-one or enum-to-int mapping mistakes between GD and Imagick drivers.","solutions":["Map your value to the supported set: only 0 (undefined), 1 (none), 2 (background), 3 (previous) are accepted; clamp or reject anything else before calling.","If you need richer disposal modes, drop to the native handle: $frame->native()->setImageDispose(Imagick::DISPOSE_BLOCK) accepts the full constant set.","Validate persisted/config-sourced disposal values with an allowlist at the boundary (config load, API deserialization) rather than at the image call site."],"exampleFix":"// before\n$frame->setDisposalMethod(Imagick::DISPOSE_BLOCK); // 7 -> InvalidArgumentException\n\n// after\n$frame->setDisposalMethod(2); // 0=undefined, 1=none, 2=background, 3=previous","handlingStrategy":"validation","validationCode":"$method = (int) $config['disposal'] ?? 0;\nif (!in_array($method, [0, 1, 2, 3], true)) {\n    throw new \\InvalidArgumentException('disposal method must be 0, 1, 2 or 3');\n}\n$frame->setDisposalMethod($method);","typeGuard":"function isValidDisposalMethod(int $method): bool\n{\n    return in_array($method, [0, 1, 2, 3], true);\n}","tryCatchPattern":"use Intervention\\Image\\Exceptions\\InvalidArgumentException;\ntry {\n    $frame->setDisposalMethod($method);\n} catch (InvalidArgumentException $e) {\n    // coerce to the supported set and retry once\n    $frame->setDisposalMethod(max(0, min($method, 3)));\n}","preventionTips":["Validate disposal values at the config/API boundary with an allowlist, not at the image call site.","Map names to values once: 'undefined'=>0, 'none'=>1, 'background'=>2, 'previous'=>3.","Never pass raw Imagick disposal constants (4+) to the driver-level API; use $frame->native()->setImageDispose() if you truly need them."],"tags":["imagick","animation","validation","invalid-argument","frame-metadata"],"backgroundTag":"argument-out-of-range","analyzedSha":"5598b9e39751c34afc5cdee84abef77f92c26f68","analyzedAt":"2026-08-23T02:17:31.068Z","schemaVersion":2},"datasetVersion":"2026-08-23T08:06:27.607Z"}