{"record":{"id":"8d72350c468ec7de","repo":"getgrav/grav","slug":"method-you-need-to-pass-option-directory","errorCode":null,"errorMessage":"__METHOD__(): You need to pass option 'directory'","messagePattern":"__METHOD__\\(\\): You need to pass option 'directory'","errorType":"exception","errorClass":"RuntimeException","httpStatus":400,"severity":"error","filePath":"system/src/Grav/Framework/Flex/FlexDirectoryForm.php","lineNumber":72,"sourceCode":"    /**\n     * @param array $options    Options to initialize the form instance:\n     *                          (string) name: Form name, allows you to use custom form.\n     *                          (string) unique_id: Unique id for this form instance.\n     *                          (array) form: Custom form fields.\n     *                          (FlexDirectory) directory: Flex Directory, mandatory.\n     *\n     * @return FlexFormInterface\n     */\n    public static function instance(array $options = []): FlexFormInterface\n    {\n        if (isset($options['directory'])) {\n            $directory = $options['directory'];\n            if (!$directory instanceof FlexDirectory) {\n                throw new RuntimeException(__METHOD__ . \"(): 'directory' should be instance of FlexDirectory\", 400);\n            }\n            unset($options['directory']);\n        } else {\n            throw new RuntimeException(__METHOD__ . \"(): You need to pass option 'directory'\", 400);\n        }\n\n        $name = $options['name'] ?? '';\n\n        return $directory->getDirectoryForm($name, $options);\n    }\n\n    /**\n     * FlexForm constructor.\n     * @param string $name\n     * @param FlexDirectory $directory\n     * @param array|null $options\n     */\n    public function __construct(string $name, FlexDirectory $directory, ?array $options = null)\n    {\n        $this->name = $name;\n        $this->setDirectory($directory);\n        $this->setName($directory->getFlexType(), $name);","sourceCodeStart":54,"sourceCodeEnd":90,"githubUrl":"https://github.com/getgrav/grav/blob/6040efed04efa69b8209448ed81308e7c24147c2/system/src/Grav/Framework/Flex/FlexDirectoryForm.php#L54-L90","documentation":"FlexDirectoryForm::instance() is a factory for directory-level (object-less) Flex forms; it requires an option named 'directory' holding a FlexDirectory instance. Omitting the option (or misspelling it) throws immediately with HTTP code 400. This is an API-contract error made by the calling code, not a runtime state problem.","triggerScenarios":"Calling FlexDirectoryForm::instance(['name' => 'login']) with no 'directory' key; passing 'directory' => 'grav-login' (a string) is caught by the sibling check, but omitting it entirely hits this line; typos like 'dir' or 'flex_directory'.","commonSituations":"Custom plugin code building a directory form for the first time; upgrading code that previously constructed FlexDirectoryForm via new and was refactored to the instance() factory; copying example code for FlexForm (object forms) and forgetting directory forms always need 'directory'.","solutions":["Resolve the directory first and pass it: $directory = $grav['flex']->getDirectory('your-type'); FlexDirectoryForm::instance(['directory' => $directory, 'name' => 'your-form']);","If you only have the type string, verify getDirectory() did not return null (unknown flex type) before calling instance().","Pass the FlexDirectory object itself, never the type string.","If you actually want an object form, use FlexForm::instance() with 'object' or 'directory'+'key'."],"exampleFix":"// before\n$form = FlexDirectoryForm::instance(['name' => 'login']);\n\n// after\n$flex = Grav::instance()['flex'];\n$form = FlexDirectoryForm::instance([\n    'directory' => $flex->getDirectory('login'),\n    'name' => 'login',\n]);","handlingStrategy":"validation","validationCode":"// Resolve and verify the directory before calling the factory\n$flex = \\Grav\\Common\\Grav::instance()['flex'];\n$directory = $flex ? $flex->getDirectory($type) : null;\nif (!$directory instanceof \\Grav\\Framework\\Flex\\FlexDirectory) {\n    throw new \\InvalidArgumentException(\"Unknown flex directory '{$type}'\");\n}\n$form = FlexDirectoryForm::instance(['directory' => $directory, 'name' => $name]);","typeGuard":"function isFlexDirectory(mixed $value): bool\n{\n    return $value instanceof \\Grav\\Framework\\Flex\\FlexDirectory;\n}","tryCatchPattern":null,"preventionTips":["Always resolve directories through $grav['flex']->getDirectory() and check for null.","Pass the FlexDirectory object, never the type string.","Wrap factory calls in a small helper that asserts the required option once."],"tags":["grav","flex","forms","invalid-argument","factory"],"backgroundTag":"missing-required-parameter","analyzedSha":"6040efed04efa69b8209448ed81308e7c24147c2","analyzedAt":"2026-08-17T05:07:31.593Z","schemaVersion":2},"datasetVersion":"2026-08-17T09:17:11.063Z"}