[5.x] Dictionaries

[duncanmcclean]

This pull request introduces the concept of Dictionaries to Statamic.

The Dictionary fieldtype works in a similar way to the Select fieldtype. However, the main difference is that the options are returned from a PHP class (called a "dictionary"), instead of being defined in the field's config.

There's a few common use cases where this is helpful:

• When you have a YAML or JSON file with options, but you don't want to enter the options into a Select field manually.
• When the options are coming from an external API of some kind. Previously, you'd need to build your own relationship fieldtype for this.
• Probably others that I haven't thought of yet...

Available Dictionaries

Statamic includes a few helpful dictionaries right out of the box:

• Countries
• Currencies
• Timezones

Building your own dictionary

It's really easy to build your own dictionary...

1. Generate a dictionary class using php please:

    php please make:dictionary Provinces

   If you want to generate a dictionary for an addon, use the --addon parameter.

2. In your app/Dictionaries directory (or src/Dictionaries in an addon), you'll see your new Provinces dictionary has been generated:

   class Provinces extends Dictionary
   
       /**
        * Returns a key/value array of options.
        *
        * @param string|null $search
        * @return array
        */
       public function options(?string $search = null): array
       {
           return $this->getItems()
               ->when($search ?? false, function ($collection) use ($search) {
                   return $collection->filter(fn ($item) => str_contains($item['name'], $search));
               })
              ->mapWithKeys(fn ($item) => [$item['slug'] => $item['name']])
               ->all();
       }
   
      /**
        * Returns a single option.
        *
        * @param string $key
        * @return string|array
        */
       public function get(string $key): string|array
       {
           return $this->getItems()->firstWhere('slug', $key);
       }
   
       private function getItems(): Collection
       {
           return collect([
               ['name' => 'January', 'slug' => 'january'],
               ['name' => 'February', 'slug' => 'february'],
               ['name' => 'March', 'slug' => 'march'],
               // ...
           ]);
       }    
   }

   • The options method should return a key/value array of all options.
     • The $search variable will be provided if the user is searching options. Feel free to search the options in whatever way works for you.
   • The get method should return a single option.
     • This will be made available when the dictionary field's options are augmented. You're free to return whatever you need here.
   • Optionally, you can also configure "config fields" for the dictionary which will be available in the dictionary's context:

       protected function fieldItems()
       {
           return [
               'region' => [
                   'display' => __('Region'),
                   'instructions' => __('statamic::messages.dictionaries_countries_region_instructions'),
                   'type' => 'select',
                   'options' => $this->getCountries()->unique('region')->pluck('region', 'region')->filter()->all(),
               ],
           ];
       }
   
       public function get(string $key): string|array
       {
           $region = $this->context['region'];
   
           // ...
       }

[jasonvarga]

I've made a whole bunch of tweaks. The initial description of this PR is fairly outdated now. The docs PR is the most up to date source now. statamic/docs#1405

tl;dr:

• Added an opinionated BasicDictionary subclass that devs can extend, making custom dictionaries way simpler. Basically just need to define an array of items.
• Added a File dictionary, letting users grab a JSON or YAML file from somewhere, throw into their app, and then they can have a custom dictionary without writing any PHP. (It should be trivial to support other file types later like xml, csv, etc)